# vargasjona/fastapi-alembic-sqlmodel-async architecture

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

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

## Overview

1. **High-level shape**
   - This is a containerized, async **FastAPI backend template** built as a modular monolith.
   - The application is split into clear layers: HTTP/API, auth and core services, persistence/models, CRUD, background jobs, and supporting infrastructure.

2. **Request entry and edge routing**
   - External traffic is meant to go through **Caddy** first.
   - Caddy acts as the reverse proxy and also serves the contents of the `static/` folder as standalone static assets.
   - The FastAPI app is exposed behind namespaced routes such as the API docs and the sample websocket/chat path described in the README.

3. **API surface**
   - The main API router is assembled under `backend/app/app/api/v1/api.py`.
   - Endpoint modules are grouped by feature area: `login`, `user`, `role`, `group`, `team`, `hero`, `report`, `cache`, `weather`, `natural_language`, and `periodic_tasks`.
   - This suggests a versioned REST API with a few non-REST samples, including async tasks, NLP/ML examples, and websocket-based chat.

4. **Domain and persistence boundary**
   - The persistence model is defined with **SQLModel / SQLAlchemy async** in `app/models/`.
   - Request/response contracts are separated into `app/schemas/` using Pydantic models.
   - CRUD logic is isolated in `app/crud/`, so endpoints call service-style data access code instead of talking directly to the database.

5. **Database access and lifecycle**
   - Async database session setup lives in `app/db/session.py`, with database initialization helpers in `app/db/init_db.py`.
   - Schema evolution is handled by **Alembic** under `backend/app/alembic/`.
   - The repo includes a seed script, `app/initial_data.py`, which creates sample users and sample domain records for teams, heroes, and groups.

6. **Authentication and authorization**
   - Authentication is JWT-based, with token schemas in `app/schemas/token_schema.py` and security helpers in `app/core/security.py` plus `app/utils/token.py`.
   - Authorization is a separate concern: `app/core/authz.polar` and `app/core/authz.py` indicate role-based policy checks.
   - Roles are a first-class domain concept, supported by dedicated models, schemas, CRUD, and dependency modules.

7. **Auxiliary dependencies and cross-cutting concerns**
   - The `app/deps/` and `app/api/deps.py` modules centralize dependency injection for things like current user, roles, group/user access, and Celery-related resources.
   - Utility code under `app/utils/` handles shared concerns such as UUID generation, schema mapping, request-local state, exceptions, image resizing, and MinIO integration.
   - This keeps the endpoints thin and pushes reusable logic out of the request handlers.

8. **Media and object storage**
   - File/image handling is modeled explicitly with `image_media` and `media` domain files.
   - The app uses a **MinIO** client for object storage, and the README describes presigned URL-based upload flows.
   - This means binary assets are not stored in PostgreSQL; the database keeps metadata while MinIO stores the actual files.

9. **Background processing and scheduled jobs**
   - Background execution is handled with **Celery**, configured in `app/core/celery.py`.
   - The architecture uses **Redis as broker** and **PostgreSQL as backend**, with periodic tasks stored via `celery-sqlalchemy-scheduler`.
   - The `natural_language` and `periodic_tasks` endpoints expose sample async/ML workloads, showing the split between synchronous API calls and deferred job execution.

10. **Testing, quality, and delivery**
   - Tests live under `backend/app/test/` and are built around **pytest** and **pytest-asyncio**.
   - Quality gates include **Black**, **Ruff**, **mypy**, and **SonarQube** configuration in the repo.
   - The project is designed for Docker Compose-based development and deployment, with CI/CD support via GitHub Actions and separate compose files for dev, test, and analysis environments.

11. **Technology boundaries to capture in a diagram**
   - HTTP clients → Caddy → FastAPI app.
   - FastAPI app → auth/deps → CRUD/services → SQLModel/PostgreSQL.
   - FastAPI app → MinIO for object storage.
   - FastAPI app → Celery/Redis/PostgreSQL for async and scheduled work.
   - Alembic and seed scripts operate on the same database but are operational, not runtime request paths.

Main entry points: [`backend/app/app/api/v1/endpoints`](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/api/v1/endpoints) (Endpoints), [`backend/app/app/db/session.py`](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/db/session.py) (DB session), [`backend/app/app/crud`](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/crud) (CRUD), [`backend/app/app/core/celery.py`](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/celery.py) (Celery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge & delivery"]
  node_caddy["Caddy<br/>reverse proxy"]
  node_static_assets["Static assets<br/>asset bundle"]
end

subgraph group_app["FastAPI app"]
  node_fastapi_main["App entry<br/>FastAPI bootstrap<br/>[main.py]"]
  node_api_router["API v1<br/>router<br/>[api.py]"]
  node_api_endpoints["Endpoints<br/>feature modules"]
  node_api_deps["API deps<br/>dependency wiring<br/>[deps.py]"]
  node_core_security["Security<br/>authn/z core<br/>[security.py]"]
  node_core_authz["Policy<br/>[authz.py]"]
end

subgraph group_data["Data layer"]
  node_crud_layer["CRUD<br/>data access"]
  node_models_layer[("Models<br/>SQLModel entities")]
  node_schemas_layer["Schemas<br/>pydantic contracts"]
  node_db_session["DB session<br/>async session<br/>[session.py]"]
  node_db_init["DB init<br/>bootstrap<br/>[init_db.py]"]
  node_minio["MinIO<br/>object storage<br/>[minio_client.py]"]
end

subgraph group_async["Async work"]
  node_celery_core["Celery<br/>worker runtime<br/>[celery.py]"]
  node_celery_deps["Celery deps<br/>worker wiring<br/>[celery_deps.py]"]
  node_redis_pg[("Redis/Postgres<br/>broker/backend")]
end

subgraph group_ops["Operations"]
  node_alembic["Alembic<br/>migrations"]
  node_seed_data["Seed data<br/>bootstrap script<br/>[initial_data.py]"]
end

node_caddy -->|"proxies HTTP"| node_fastapi_main
node_caddy -->|"serves assets"| node_static_assets
node_fastapi_main -->|"mounts"| node_api_router
node_api_router -->|"includes"| node_api_endpoints
node_api_endpoints -->|"uses deps"| node_api_deps
node_api_endpoints -->|"authn/z"| node_core_security
node_core_security -->|"enforces policy"| node_core_authz
node_api_endpoints -->|"calls"| node_crud_layer
node_api_endpoints -->|"validates"| node_schemas_layer
node_crud_layer -->|"maps"| node_models_layer
node_crud_layer -->|"queries"| node_db_session
node_db_session -->|"persists"| node_models_layer
node_db_init -->|"initializes"| node_db_session
node_alembic -->|"migrates"| node_models_layer
node_seed_data -->|"seeds"| node_db_session
node_api_endpoints -->|"uploads"| node_minio
node_api_endpoints -->|"dispatches tasks"| node_celery_core
node_celery_core -->|"configured by"| node_celery_deps
node_celery_core -->|"uses broker/backend"| node_redis_pg
node_api_endpoints -.->|"stores job state"| node_redis_pg

click node_caddy "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/caddy/Caddyfile"
click node_static_assets "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/static"
click node_fastapi_main "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/main.py"
click node_api_router "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/api/v1/api.py"
click node_api_endpoints "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/api/v1/endpoints"
click node_api_deps "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/api/deps.py"
click node_core_security "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/security.py"
click node_core_authz "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/authz.py"
click node_crud_layer "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/crud"
click node_models_layer "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/models"
click node_schemas_layer "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/schemas"
click node_db_session "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/db/session.py"
click node_db_init "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/db/init_db.py"
click node_alembic "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/alembic"
click node_seed_data "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/initial_data.py"
click node_minio "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/utils/minio_client.py"
click node_celery_core "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/celery.py"
click node_celery_deps "https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/deps/celery_deps.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_caddy,node_static_assets toneBlue
class node_fastapi_main,node_api_router,node_api_endpoints,node_api_deps,node_core_security,node_core_authz toneAmber
class node_crud_layer,node_models_layer,node_schemas_layer,node_db_session,node_db_init,node_minio toneMint
class node_celery_core,node_celery_deps,node_redis_pg toneRose
class node_alembic,node_seed_data toneIndigo
```

## Components

### Edge & delivery

Ingress proxy and static asset serving

- [Caddy](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/caddy/Caddyfile): reverse proxy · Ingress proxy and static asset server · `caddy/Caddyfile`
- [Static assets](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/static): asset bundle · Standalone files served by Caddy · `static`

### FastAPI app

HTTP API, auth, and domain modules

- [App entry](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/main.py): FastAPI bootstrap · Application startup and router assembly · `backend/app/app/main.py`
- [API v1](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/api/v1/api.py): router · Versioned API composition · `backend/app/app/api/v1/api.py`
- [Endpoints](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/api/v1/endpoints): feature modules · Login, user, role, group, team, hero, report, cache, weather, NLP, periodic tasks · `backend/app/app/api/v1/endpoints`
- [API deps](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/api/deps.py): dependency wiring · Shared request dependencies and access controls · `backend/app/app/api/deps.py`
- [Security](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/security.py): authn/z core · JWT and authorization helpers · `backend/app/app/core/security.py`
- [Policy](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/authz.py): authorization policy · Role-based policy rules · `backend/app/app/core/authz.py`

### Data layer

Persistence models, schemas, CRUD, and database lifecycle

- [CRUD](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/crud): data access · Service-style persistence operations · `backend/app/app/crud`
- [Models](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/models): SQLModel entities · Domain persistence models · `backend/app/app/models`
- [Schemas](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/app/schemas): pydantic contracts · Request and response schemas · `backend/app/app/schemas`
- [DB session](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/db/session.py): async session · Async database session and engine setup · `backend/app/app/db/session.py`
- [DB init](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/db/init_db.py): bootstrap · Database initialization helpers · `backend/app/app/db/init_db.py`
- [MinIO](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/utils/minio_client.py): object storage · Binary asset storage for media uploads · `backend/app/app/utils/minio_client.py`

### Async work

Background jobs and scheduled execution

- [Celery](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/core/celery.py): worker runtime · Background and periodic task runtime · `backend/app/app/core/celery.py`
- [Celery deps](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/deps/celery_deps.py): worker wiring · Task and worker dependency helpers · `backend/app/app/deps/celery_deps.py`
- **Redis/Postgres**: broker/backend · Celery broker and result backend storage

### Operations

Schema migrations and bootstrap data

- [Alembic](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/tree/main/backend/app/alembic): migrations · Schema migrations · `backend/app/alembic`
- [Seed data](https://github.com/vargasjona/fastapi-alembic-sqlmodel-async/blob/main/backend/app/app/initial_data.py): bootstrap script · Creates sample users and domain records · `backend/app/app/initial_data.py`

## Connections

- Caddy → App entry: proxies HTTP · External requests are routed through Caddy to the app
- Caddy → Static assets: serves assets · Caddy serves standalone static content
- App entry → API v1: mounts · Main app assembles the versioned API router
- API v1 → Endpoints: includes · Router is composed from feature endpoint modules
- Endpoints → API deps: uses deps · Endpoints rely on shared dependency injection
- Endpoints → Security: authn/z · Routes use JWT and security helpers
- Security → Policy: enforces policy · Security layer consults authorization rules
- Endpoints → CRUD: calls · Handlers delegate persistence logic to CRUD layer
- Endpoints → Schemas: validates · Request and response payloads use Pydantic schemas
- CRUD → Models: maps · CRUD operates on SQLModel entities
- CRUD → DB session: queries · Data access uses async sessions
- DB session → Models: persists · Models are stored in the application database
- DB init → DB session: initializes · Database bootstrap builds on session configuration
- Alembic → Models: migrates · Migrations evolve the same schema used by models
- Seed data → DB session: seeds · Seed script writes sample data through the database layer
- Endpoints → MinIO: uploads · Media endpoints use object storage for binaries
- Endpoints → Celery: dispatches tasks · Async and periodic workloads are sent to Celery
- Celery → Celery deps: configured by · Worker runtime is wired through dependency helpers
- Celery → Redis/Postgres: uses broker/backend · Celery relies on Redis and PostgreSQL infrastructure
- Endpoints → Redis/Postgres: stores job state · Periodic task patterns involve shared backend storage
