Gezen Backend (Sword API)

FastAPI backend application for managing factories, machines, quotes, tasks, and digital competency assessments.

Features

• Factory and machine tracking
• Dynamic quote creation with ReportLab PDF export
• Task and calendar event scheduling
• Digital competency evaluations and ROI calculations
• Expo mobile push notifications
• Microsoft Graph API email integration
• JWT authentication with Admin and Consultant roles

Tech Stack

• FastAPI
• PostgreSQL with SQLAlchemy ORM
• Alembic
• Pytest (SQLite in-memory)
• Sentry

Project Structure

.
├── alembic_clean/        # Active Alembic migration scripts
├── alembic/              # Legacy Alembic migration tree; do not add new revisions here
├── assets/               # Static images, videos, and PDFs used by the app
├── app/
│   ├── auth.py           # Authentication, JWT, and RBAC
│   ├── crud.py           # Database operations
│   ├── database.py       # Database connection setup
│   ├── models.py         # SQLAlchemy ORM models
│   └── schemas.py        # Pydantic schemas
├── docs/                 # Deployment and analysis documentation
├── requirements/         # Dependency files (dev/runtime)
├── scripts/
│   └── shell/            # Deployment and maintenance shell scripts
├── tests/                # Pytest suite
├── utils/                # PDF generation and Email sending
├── main.py               # Main router and API endpoints
└── AGENTS.md             # AI Agent architecture and instructions

Helpful Paths

• Documentation: docs/DEPLOYMENT.md, docs/LOCAL_DEPLOYMENT.md, docs/code-analysis.md, docs/analysis_report.md
• Shell Scripts: scripts/shell/deploy_https.sh, scripts/shell/deploy_https_local.sh, scripts/shell/master_deploy.sh, scripts/shell/master_deploy_local.sh, scripts/shell/setup_database.sh, scripts/shell/run_migrations.sh
• Assets: assets/images/, assets/videos/, assets/pdfs/
• Dependencies: requirements/dev.txt, requirements/runtime.txt

Local Development Setup

1. Clone the repository

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements/dev.txt
   

4. Create a .env file in the root directory:

   DATABASE_URL=postgresql://user:password@localhost/dbname
   SECRET_KEY=your_secret_key
   ACCESS_TOKEN_EXPIRE_MINUTES=1440
   OPENAI_API_KEY=your_openai_key
   SENTRY_DSN=your_sentry_dsn
   AZURE_CLIENT_ID=your_client_id
   AZURE_TENANT_ID=your_tenant_id
   AZURE_CLIENT_SECRET=your_client_secret
   

5. Run database migrations:

   alembic upgrade head
   

6. Start the server:

   Localhost only (same machine):

   uvicorn main:app --reload
   

   Local deployment on a LAN IP (phones and other devices on your network):

   venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --reload
   

   Use --host 0.0.0.0 to listen on all interfaces, then reach the API at http://<your-machine-ip>:8000. Replace 0.0.0.0 with a specific IP if you only want one interface.

API Documentation

• Swagger UI: http://127.0.0.1:8000/api/docs
• ReDoc: http://127.0.0.1:8000/api/redoc

Testing

Run tests using pytest:

pytest tests/

Migration Caveat

alembic.ini points to alembic_clean/, so new database revisions must be created under alembic_clean/versions. The older alembic/versions tree is legacy and should not receive new migrations unless the project intentionally switches back to that migration graph.

The clean baseline migration imports the current SQLAlchemy metadata, so migrations that follow it may need to be idempotent when they bridge existing baseline-stamped databases and fresh databases created from the latest models.

Public Docs Site

The public documentation site is generated from the docs/ folder and published with GitHub Pages.

• Public site: https://iqvizyon-development.github.io/gezen-backend/
• Local preview: pip install -r requirements/docs.txt && mkdocs serve
• GitHub setting: enable Pages from the gh-pages branch at root
• Language switcher: English / Türkçe