# projecttech4devai/ai-platform architecture

> Architecture diagram of the GitHub repository projecttech4devai/ai-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/projecttech4devai/ai-platform
- Repository: https://github.com/projecttech4devai/ai-platform

## Overview

##### Project type and purpose
- This is a monolithic backend service built with FastAPI (Python) that provides a RESTful API for an AI Platform.
- It handles user management, organizations, projects, API keys, document/collection storage, AI conversations (via OpenAI), email notifications, and benchmarking CLI commands.
- It uses Docker Compose for local development and deployment, Alembic for database migrations, and Postgres as its primary data store.

##### File structure
- Top level: configuration files (`.env.example`, `docker-compose.yml`, CI/CD workflows, scripts), project‐wide docs, deployment and development guides.
- `backend/`: the entire application lives here.
- `app/main.py` launches the FastAPI app.
- `app/api/`: defines routes, dependencies, and autogenerated markdown docs per endpoint.
- `app/crud/`: data access layer interacting with SQLAlchemy models.
- `app/models/`: ORM models representing database tables.
- `app/core/`: configuration, security, middleware, logging, cloud storage abstraction, OpenAI provider, Langfuse integration.
- `app/email-templates/`: MJML templates compiled to HTML for outbound emails.
- `app/cli/`: command-line benchmarking tools.
- `alembic/`: migration scripts and environment for schema evolution.
- `scripts/` & `backend/scripts/`: convenience shell scripts for linting, testing, prestart, deployments.
- Docker: `backend/Dockerfile`, `.dockerignore`.
- Deployment: `docker-compose.yml` (+ overrides), `deployment.md`, CD workflows in `.github/workflows`.

##### README for additional insights
- Confirms use of Docker Compose for “watch” mode and Uvicorn, Postgres, environment‐driven configuration, and template origin (full‐stack FastAPI template).
- Points to separate backend README and deployment/development guides.
- No bundled frontend—focus is purely the API and CLI.

##### Main components
a. FastAPI Application
- Routers (app/api/routes)
- Dependency injection (app/api/deps)
- Middleware, exception handlers, security (app/core)
b. Data Layer
- SQLAlchemy ORM models (app/models)
- Alembic migrations (backend/alembic)
- Postgres database
c. Core & Utilities
- Configuration, logging, util functions (app/core)
- Cloud storage abstraction (e.g., S3)
- Email template compiler & SMTP or transactional email service
- External AI provider (OpenAI, via app/core/providers.py)
- Langfuse telemetry integration
d. CLI Benchmarking Tool
- Entrypoint (app/cli/main.py)
- Commands and test datasets (app/cli/bench)
e. External Services
- OpenAI API
- Email/SMTP provider
- Object storage (via cloud/storage.py)
- Langfuse analytics endpoint
f. DevOps & CI/CD
- Docker Compose services (FastAPI, Postgres, Traefik)
- GitHub Actions workflows
- Build and deployment scripts

##### Relationships and interactions
- User/client → FastAPI (HTTP REST calls)
- FastAPI → Postgres (ORM CRUD operations)
- FastAPI → Alembic (at startup or CI for migrations)
- FastAPI → Cloud storage (upload/download documents)
- FastAPI → OpenAI API (chat, embeddings)
- FastAPI → Langfuse (logging telemetry)
- FastAPI → Email service (send password resets, account invites)
- CLI tool → FastAPI or DB directly (depending on the command)
- Docker Compose orchestrates FastAPI, Postgres, reverse proxy (Traefik)

##### Architectural patterns & principles
- Layered architecture: API → service/deps → CRUD → models → database
- Clear separation of concerns: core/config, API routes, data access, utilities, CLI
- Migrations decoupled via Alembic
- Environment‐driven configuration for 12-factor compliance
- Containerized services for consistency across environments

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Backend Service
  subgraph "Backend Service"
    direction TB

    subgraph "API Layer"
      direction TB
      FastAPI["FastAPI App (Uvicorn)"]:::internal
      PreStart["Pre-start Hook"]:::internal
      Routers["API Routers"]:::internal
      Deps["API Dependencies"]:::internal
      Docs["Auto-generated API Docs"]:::internal
    end

    subgraph "CRUD & Data"
      direction TB
      CRUD["CRUD Layer"]:::internal
      Models["SQLAlchemy ORM Models"]:::internal
      Migrations["Alembic Migrations"]:::document
    end

    subgraph "Core & Utils"
      direction TB
      Config["Application Configuration"]:::internal
      Security["Security Utilities"]:::internal
      Middleware["Custom Middleware"]:::internal
      Exceptions["Exception Handlers"]:::internal
      Logger["Logging Setup"]:::internal
      CloudStorage["Cloud Storage Abstraction"]:::internal
      OpenAIProv["OpenAI Provider Integration"]:::internal
      Langfuse["Langfuse Telemetry Integration"]:::internal
      DBSession["Core DB Session Utility"]:::internal
      Util["General Utility Functions"]:::internal
      EmailTemplates["Email Templates"]:::document
    end

    subgraph "CLI & Seeders"
      direction TB
      CLI["CLI Benchmarking Tool"]:::internal
      Bench["Benchmark Commands & Data"]:::internal
      InitialData["Initial Data Seeder"]:::internal
      InitialStorage["Initial Storage Seeder"]:::internal
    end
  end

  %% External Services
  subgraph "External Services"
    direction TB
    Postgres["Postgres DB"]:::external
    OpenAIAPI["OpenAI API"]:::external
    EmailService["Email/SMTP Service"]:::external
    StorageService["Object Storage"]:::external
    LangfuseAPI["Langfuse Analytics"]:::external
  end

  %% DevOps & CI/CD
  subgraph "DevOps & CI/CD"
    direction TB
    DockerCompose["Docker Compose"]:::devops
    DockerfileNode["Dockerfile"]:::devops
    GitHubActions["GitHub Actions Workflows"]:::devops
    Guides["Dev & Deployment Guides"]:::devops
  end

  %% Connections
  Client["User / Client"]:::external -->|HTTP REST| FastAPI
  FastAPI -->|uses| Routers
  FastAPI -->|injects| Deps
  FastAPI -->|serves| Docs
  FastAPI -->|executes| PreStart

  Routers -->|calls| CRUD
  Deps -->|provides sessions| DBSession
  CRUD -->|reads/writes| Models
  CRUD -->|reads/writes| Postgres
  Migrations -->|migrate| Postgres
  FastAPI -->|executes migrations| Migrations

  FastAPI -->|loads| Config
  FastAPI -->|applies| Middleware
  FastAPI -->|handles errors| Exceptions
  FastAPI -->|logs to| Logger

  FastAPI -->|calls| CloudStorage
  CloudStorage -->|REST| StorageService

  FastAPI -->|calls| OpenAIProv
  OpenAIProv -->|HTTP POST| OpenAIAPI

  FastAPI -->|sends telemetry| Langfuse
  Langfuse -->|HTTP POST| LangfuseAPI

  FastAPI -->|renders| EmailTemplates
  EmailTemplates -->|SMTP| EmailService

  CLI -->|calls API or direct DB| FastAPI
  CLI -->|uses| DBSession
  CLI -->|runs| Bench

  CLI -->|runs| InitialData
  CLI -->|runs| InitialStorage

  DockerCompose -->|orchestrates| FastAPI
  DockerCompose -->|orchestrates| Postgres
  DockerCompose -->|orchestrates| GitHubActions

  GitHubActions -->|runs builds| DockerCompose
  Guides -->|documents| DockerCompose

  %% Click Events
  click FastAPI "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/main.py"
  click PreStart "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/backend_pre_start.py"
  click Routers "https://github.com/projecttech4devai/ai-platform/tree/main/backend/app/api/routes/"
  click Deps "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/api/deps.py"
  click Docs "https://github.com/projecttech4devai/ai-platform/tree/main/backend/app/api/docs/"
  click CRUD "https://github.com/projecttech4devai/ai-platform/tree/main/backend/app/crud/"
  click Models "https://github.com/projecttech4devai/ai-platform/tree/main/backend/app/models/"
  click Migrations "https://github.com/projecttech4devai/ai-platform/tree/main/backend/app/alembic/"
  click Config "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/core/config.py"
  click Security "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/core/security.py"
  click Middleware "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/core/middleware.py"
  click Exceptions "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/core/exception_handlers.py"
  click Logger "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/core/logger.py"
  click CloudStorage "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/core/cloud/storage.py"
  click OpenAIProv "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/core/providers.py"
  click Langfuse "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/core/langfuse/langfuse.py"
  click DBSession "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/core/db.py"
  click Util "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/core/util.py"
  click EmailTemplates "https://github.com/projecttech4devai/ai-platform/tree/main/backend/app/email-templates/src/"
  click CLI "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/cli/main.py"
  click Bench "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/cli/bench/commands.py"
  click InitialData "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/initial_data.py"
  click InitialStorage "https://github.com/projecttech4devai/ai-platform/blob/main/backend/app/initial_storage.py"
  click DockerfileNode "https://github.com/projecttech4devai/ai-platform/tree/main/backend/Dockerfile"
  click DockerCompose "https://github.com/projecttech4devai/ai-platform/blob/main/docker-compose.yml"
  click GitHubActions "https://github.com/projecttech4devai/ai-platform/tree/main/.github/workflows/"
  click Guides "https://github.com/projecttech4devai/ai-platform/blob/main/development.md"

  %% Styles
  classDef internal fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
  classDef external fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
  classDef devops fill:#ffe0b2,stroke:#f57c00,color:#e65100
  classDef document fill:#eeeeee,stroke:#9e9e9e,color:#424242
```
