# jonra1993/fastapi-alembic-sqlmodel-async architecture

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

- Interactive diagram: https://gitdiagram.com/jonra1993/fastapi-alembic-sqlmodel-async
- Repository: https://github.com/jonra1993/fastapi-alembic-sqlmodel-async

## Overview

##### Project Type and Purpose
- This is a backend-focused, full-stack microservice template.
- It provides an async FastAPI REST API with JWT auth, role-based access control, SQLModel (SQLAlchemy) migrations (Alembic), object storage (Minio), a reverse proxy (Caddy), a task queue (Celery + Redis), and Docker Compose orchestration.
- It also includes testing, static analysis (SonarQube), and code-style tooling.

##### Key Components to Model
a. Reverse Proxy & Static Server
- Caddy container (Caddyfile)
- Serves `/docs`, `/static`, WebSocket endpoints
b. FastAPI Application
- API routers (`app/api/v1/endpoints`)
- Core modules (`authz`, `security`, `config`)
- CRUD layer, Pydantic/SQLModel schemas & SQLModel models
- Dependency injections
c. Persistence Layer
- PostgreSQL database (docker-compose, `create-dbs.sql`)
- Alembic migrations (`alembic/versions`)
d. Object Storage
- Minio container (S3-compatible buckets)
e. Async Tasks
- Celery workers + Celery Beat
- Redis broker & result backend
- Task definitions (`celery_task.py`, `periodic_tasks` endpoints)
f. Auxiliary Services
- pgAdmin (database GUI)
- SonarQube (static analysis)
- Local host environment variables (`.env.example`)
- Docker Compose files for dev, test, prod

##### Relationships & Data Flows
- Caddy ← HTTP/HTTPS → FastAPI
- FastAPI ←→ Postgres (SQLModel ORM)
- FastAPI ←→ Minio (via presigned URLs)
- FastAPI → Redis broker (enqueue tasks)
- Celery workers ← Redis broker & → Postgres (for task results via celery-sqlalchemy-scheduler)
- Celery Beat ← schedules tasks → Celery workers
- External clients ↔ WebSocket endpoint on FastAPI

##### Architectural Patterns & Design Principles
- Separation of Concerns: API, auth, data access, background tasks
- Dependency Injection: FastAPI `Depends` in `deps.py` modules
- Async Programming: Async SQLModel engine + async def endpoints
- Containerization: Each major component runs in a separate Docker container
- Infrastructure as Code: Docker Compose, Makefile, Caddyfile

- Environment variable dependency (.env) feeding into FastAPI & Celery
- Static hosting path (`/static`) on Caddy
- Alembic migrations interacting with Postgres
- Testing and CI/CD flows if desired (SonarQube, GitHub Actions)

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef proxy fill:#ccf,stroke:#333,stroke-width:1px
    classDef backend fill:#cfc,stroke:#333,stroke-width:1px
    classDef database fill:#fcf,stroke:#333,stroke-width:1px
    classDef service fill:#ffc,stroke:#333,stroke-width:1px
    classDef config fill:#eef,stroke:#333,stroke-width:1px

    Client["Clients (HTTP/HTTPS/WebSocket)"]:::external
    subgraph "Container Orchestration"
        Caddy["Caddy Reverse Proxy & Static\n(/static, /docs)"]:::proxy
        StaticAssets["Static Assets"]:::proxy
        FastAPIBox["FastAPI Server\n(async uvicorn)"]:::backend
        CeleryBeat["Celery Beat\n(Scheduler)"]:::backend
        CeleryWorker["Celery Workers"]:::backend
        Postgres["PostgreSQL"]:::database
        Redis["Redis\n(Broker & Result)"]:::database
        Minio["Minio\n(Object Storage)"]:::database
        pgAdmin["pgAdmin"]:::service
        Sonar["SonarQube"]:::service
        env[".env"]:::config
    end

    Client -->|"HTTP/HTTPS/WebSocket"| Caddy
    Caddy -->|"serves static"| StaticAssets
    Caddy -->|"HTTP"| FastAPIBox
    FastAPIBox -->|"SQL"| Postgres
    FastAPIBox -->|"S3 API"| Minio
    FastAPIBox -->|"AMQP"| Redis
    CeleryBeat -->|"AMQP schedule"| Redis
    CeleryBeat -->|"schedule tasks"| CeleryWorker
    CeleryWorker -->|"SQL"| Postgres
    CeleryWorker -->|"AMQP results"| Redis
    env --> FastAPIBox
    env --> CeleryBeat
    env --> CeleryWorker

    click Caddy "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/caddy/Caddyfile"
    click StaticAssets "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/static/"
    click FastAPIBox "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/main.py"

    %% FastAPI Application Subcomponents
    subgraph "FastAPI App Components" 
        API["API Routers (v1)"]:::backend
        Endpoints["API Endpoints"]:::backend
        Deps["Dependency Injection Modules"]:::backend
        ConfigCore["Core Config & Security"]:::backend
        Authz["Authorization (Polar & Policy)"]:::backend
        DBSess["DB Session & Init"]:::backend
        Alembic["Alembic Migrations"]:::backend
        CRUD["SQLModel CRUD"]:::backend
        Models["SQLModel Models"]:::backend
        Schemas["Pydantic/SQLModel Schemas"]:::backend
        MinioClient["Minio Object Storage Client"]:::backend
        Utils["Utility Modules"]:::backend
    end

    FastAPIBox --> API
    FastAPIBox --> Deps
    FastAPIBox --> ConfigCore
    FastAPIBox --> Authz
    FastAPIBox --> DBSess
    FastAPIBox --> Alembic
    FastAPIBox --> CRUD
    FastAPIBox --> Models
    FastAPIBox --> Schemas
    FastAPIBox --> MinioClient
    FastAPIBox --> Utils
    API --> Endpoints

    click API "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/api/v1/api.py"
    click Endpoints "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/api/v1/endpoints/"
    click Deps "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/api/deps.py"
    click Deps "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/deps/"
    click ConfigCore "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/config.py"
    click ConfigCore "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/security.py"
    click Authz "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/authz.polar"
    click Authz "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/authz.py"
    click DBSess "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/db/session.py"
    click DBSess "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/db/init_db.py"
    click Alembic "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/alembic/"
    click Alembic "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/alembic/versions/"
    click CRUD "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/crud/"
    click Models "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/models/"
    click Schemas "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/schemas/"
    click MinioClient "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/utils/minio_client.py"
    click Utils "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/utils/"

    click CeleryBeat "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/celery.py"
    click CeleryWorker "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/celery.py"
    click CeleryTaskDef "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/api/celery_task.py"
    click CeleryTaskDef "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/api/celery_task.py"
    click CeleryDeps "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/deps/celery_deps.py"

    click Postgres "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/create-dbs.sql"
    click pgAdmin "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/pgadmin.yml"
    click Sonar "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/backend/sonar-project.properties"
    click Sonar "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/docker-compose-sonarqube.yml"
    click env "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/.env.example"
    click DockerCompose "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/docker-compose.yml"
    click DockerCompose "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/docker-compose-dev.yml"
    click DockerCompose "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/docker-compose-test.yml"
    click DockerCompose "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/docker-compose-sonarqube.yml"
    click Dockerfile "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/backend/Dockerfile"
    click Makefile "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/tree/main/Makefile"
    click CI1 "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/.github/workflows/main.yml"
    click CI2 "https://github.com/jonra1993/fastapi-alembic-sqlmodel-async/blob/main/.github/workflows/deploy_docs.yml"
    
    class DockerCompose service
    class Dockerfile,Makefile,CI1,CI2 config
```
