# cssfr/fastapi-poc-backend architecture

> Architecture diagram of the GitHub repository cssfr/fastapi-poc-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cssfr/fastapi-poc-backend
- Repository: https://github.com/cssfr/fastapi-poc-backend

## Overview

##### Main components
a. API Layer
- FastAPI app (“app/main.py”)
- Middleware, authentication (app/auth.py, app/middleware.py)
- Routers:
– OHLCV router (app/routers/ohlcv.py)
– Storage router (app/routers/storage.py)
- Health check endpoint (app/health.py)
b. Service Layer
- Business logic (app/services.py)
- DuckDB analytics service (app/duckdb_service.py)
- Supabase Storage client (app/minio_client.py)
c. Data Persistence
- PostgreSQL (Supabase) via SQLAlchemy (app/database.py, app/models.py, app/models_ohlcv.py)
- Migrations (alembic/ + alembic.ini)
d. External Services
- Supabase Postgres (env var DATABASE_URL)
- Supabase Storage (S3-compatible; auth via SUPABASE_URL + JWT_SECRET)
e. Dev/Deployment
- Dockerfile & start.sh
- .devcontainer for VS Code
- Requirements.txt, uvicorn run command

##### Relationships and data flows
- Client → FastAPI (uvicorn) → Routes → Services →
– ↳ PostgreSQL (read/write via SQLAlchemy)
– ↳ DuckDB (for analytics queries)
– ↳ Supabase Storage (via MinIO client for object upload/download)
- Alembic migrations run against PostgreSQL at build/deploy time
- Health check and logging are cross-cutting concerns

##### Architectural patterns
- Layered architecture:
– Presentation/API layer (FastAPI + routers + middleware)
– Service/Domain layer (business logic, data-access services)
– Data layer (ORM models, migrations, external DB/storage)
- Dependency injection/configuration via environment variables
- Separation of concerns:
– Auth, Logging, Health, Business, Data

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application" 
        direction TB
        Main["FastAPI App\n(app/main.py)"]:::api
        Auth["Authentication Module\n(app/auth.py)"]:::api
        Middleware["Middleware\n(app/middleware.py)"]:::api
        Health["Health Check Endpoint\n(app/health.py)"]:::api
        subgraph "Routers"
            direction TB
            OHLCV["OHLCV Router\n(app/routers/ohlcv.py)"]:::api
            StorageAPI["Storage Router\n(app/routers/storage.py)"]:::api
        end
        subgraph "Services"
            direction TB
            Business["Business Logic\n(app/services.py)"]:::service
            DuckDB["DuckDB Analytics Service\n(app/duckdb_service.py)"]:::service
            MinIO["Supabase Storage Client\n(app/minio_client.py)"]:::service
        end
        Exceptions["Exception Definitions\n(app/exceptions.py)"]:::api
        Logging["Logging Config\n(app/logging_config.py)"]:::api
        DatabaseSetup["DB Setup\n(app/database.py)"]:::data
        Models["ORM Models\n(app/models.py)"]:::data
        ModelsOHLCV["OHLCV Models\n(app/models_ohlcv.py)"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Postgres["Supabase Postgres"]:::external
        Storage["Supabase Storage (S3)"]:::external
    end

    %% Migrations
    subgraph "Migrations\n(alembic/)"
        direction TB
        AlembicIni["alembic.ini"]:::infra
        AlembicEnv["env.py"]:::infra
        AlembicScript["script.py.mako"]:::infra
        VersionsDir["versions/"]:::infra
        InitialMigration["001_initial_schema.py"]:::infra
    end

    %% Dev & Deployment
    subgraph "Dev/Infra"
        direction TB
        DockerfileNode["Dockerfile"]:::infra
        DevContainer[".devcontainer/devcontainer.json"]:::infra
        StartScript["start.sh"]:::infra
        Requirements["requirements.txt"]:::infra
        Uvicorn["uvicorn run"]:::infra
    end

    %% Client
    Client["API Client\n(CLI/Web UI)"]:::external

    %% Relationships
    Client -->|"HTTP Request"| Main
    Main --> Auth
    Main --> Middleware
    Main --> Health
    Main --> OHLCV
    Main --> StorageAPI
    OHLCV -->|"calls"| Business
    StorageAPI -->|"calls"| Business
    Business --> DatabaseSetup
    Business --> DuckDB
    Business --> MinIO
    DatabaseSetup --> Models
    DatabaseSetup --> ModelsOHLCV
    DatabaseSetup --> Postgres
    DuckDB -->|"Analytics Query"| Postgres
    MinIO -->|"PUT/GET Object"| Storage
    AlembicIni --> VersionsDir
    AlembicEnv --> VersionsDir
    AlembicScript --> VersionsDir
    VersionsDir --> InitialMigration
    InitialMigration --> Postgres
    DockerfileNode --> Main
    DockerfileNode --> AlembicIni
    StartScript --> Main
    DevContainer --> DockerfileNode
    Requirements --> Main
    Uvicorn --> Main

    %% Click Events
    click Main "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/main.py"
    click Auth "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/auth.py"
    click Middleware "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/middleware.py"
    click Health "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/health.py"
    click OHLCV "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/routers/ohlcv.py"
    click StorageAPI "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/routers/storage.py"
    click Business "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/services.py"
    click DuckDB "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/duckdb_service.py"
    click MinIO "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/minio_client.py"
    click DatabaseSetup "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/database.py"
    click Models "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/models.py"
    click ModelsOHLCV "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/models_ohlcv.py"
    click AlembicIni "https://github.com/cssfr/fastapi-poc-backend/blob/master/alembic.ini"
    click AlembicEnv "https://github.com/cssfr/fastapi-poc-backend/blob/master/alembic/env.py"
    click AlembicScript "https://github.com/cssfr/fastapi-poc-backend/blob/master/alembic/script.py.mako"
    click VersionsDir "https://github.com/cssfr/fastapi-poc-backend/tree/master/alembic/versions/"
    click InitialMigration "https://github.com/cssfr/fastapi-poc-backend/blob/master/alembic/versions/001_initial_schema.py"
    click Logging "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/logging_config.py"
    click Exceptions "https://github.com/cssfr/fastapi-poc-backend/blob/master/app/exceptions.py"
    click DockerfileNode "https://github.com/cssfr/fastapi-poc-backend/tree/master/Dockerfile"
    click DevContainer "https://github.com/cssfr/fastapi-poc-backend/blob/master/.devcontainer/devcontainer.json"
    click StartScript "https://github.com/cssfr/fastapi-poc-backend/blob/master/start.sh"
    click Requirements "https://github.com/cssfr/fastapi-poc-backend/blob/master/requirements.txt"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef service fill:#DFFFD0,stroke:#228B22,stroke-width:1px
    classDef data fill:#FFE0B2,stroke:#FF8C00,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#666666,stroke-width:1px
    classDef infra fill:#F3E5F5,stroke:#9C27B0,stroke-width:1px
```
