How vargasjona/fastapi-alembic-sqlmodel-async works
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: endpoints Endpoints · session.py DB session · crud CRUD · celery.py Celery
Components 19
Edge & delivery
Ingress proxy and static asset serving
- Caddy · Ingress proxy and static asset server
caddy/Caddyfile - Static assets · Standalone files served by Caddy
static
FastAPI app
HTTP API, auth, and domain modules
- App entry · Application startup and router assembly
backend/app/app/main.py - API v1 · Versioned API composition
backend/app/app/api/v1/api.py - Endpoints · Login, user, role, group, team, hero, report, cache, weather, NLP, periodic tasks
backend/app/app/api/v1/endpoints - API deps · Shared request dependencies and access controls
backend/app/app/api/deps.py - Security · JWT and authorization helpers
backend/app/app/core/security.py - Policy · Role-based policy rules
backend/app/app/core/authz.py
Data layer
Persistence models, schemas, CRUD, and database lifecycle
- CRUD · Service-style persistence operations
backend/app/app/crud - Models · Domain persistence models
backend/app/app/models - Schemas · Request and response schemas
backend/app/app/schemas - DB session · Async database session and engine setup
backend/app/app/db/session.py - DB init · Database initialization helpers
backend/app/app/db/init_db.py - MinIO · Binary asset storage for media uploads
backend/app/app/utils/minio_client.py
Async work
Background jobs and scheduled execution
- Celery · Background and periodic task runtime
backend/app/app/core/celery.py - Celery deps · Task and worker dependency helpers
backend/app/app/deps/celery_deps.py - Redis/Postgres · Celery broker and result backend storage
Connections 20
- 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