How deight93/fastapi-boilerplate works
Project Type & Purpose
• This is a monolithic backend web API written in Python using FastAPI.
• Primary features: administrator panel, user registration/login, JWT-based auth, token refresh, basic static content.
• It runs in containers (Docker) and uses PostgreSQL for persistence, Redis for caching/sessions, and Alembic for schema migrations.
Key File-Tree Insights
• Top-level:
• Dockerfile, docker-compose.yml (+ override/prod) → containerized deployment.
• alembic.ini & migrations/ → database migration setup.
• app/ → main code, subdivided into core (config, middleware, logging), routers (HTTP endpoints), services (business logic), models (ORM), schemas (Pydantic models), admin UI, static assets.
• tests/ → pytest suite.
• Core principles: layered architecture (router → service → model/DB), dependency injection, middleware for cross-cutting concerns, environment-driven configuration.
Extracted Technologies & Frameworks
• Runtime: Uvicorn (via “uv”), FastAPI
• Data layer: SQLAlchemy (in app/models + core/database), Alembic for migrations
• Caching/session: Redis
• Auth: JWT (app/core/security + app/services/auth)
• Admin UI: custom pages in app/admin served by FastAPI
• Dev tooling: uv, ruff (lint), pre-commit, pytest, GitHub Actions CI
Main Components & Their Roles
A. HTTP Client (e.g., Browser or API client)
B. Load Balancer / Reverse Proxy (optional – e.g., nginx)
C. Uvicorn Server running the FastAPI application
1. Routers (app/routers) – maps HTTP paths to handlers
2. Middleware & Dependency Injection (app/core/middleware + core/dependency)
3. Services (app/services) – business logic (auth, user management)
4. Models & DB Layer (app/models + core/database) – ORM + SQLAlchemy sessions
5. Schemas (app/schemas) – request/response validation (Pydantic)
6. Admin UI & Static Content (app/admin + app/core/static)
D. Datastore: PostgreSQL (Docker service “postgresql-db”)
E. Cache/Session Store: Redis (Docker service “redis-db”)
F. Migration Tool: Alembic (invoked during startup/deployment)
G. CI/CD Pipeline: GitHub Actions (runs uv sync, ruff, pytest)
Component Interactions
• HTTP Client → (LB) → Uvicorn/FastAPI
• FastAPI → Routers → Services → Models → PostgreSQL
• Auth Services → Redis (storing refresh tokens or session data)
• FastAPI → Admin UI controllers → static assets served directly or via CDN
• Deployment: Docker Compose spins up API, Postgres, Redis in a shared network
• CI/CD: On push, GitHub Actions container runs tests against a transient Docker Compose environment
Architectural Patterns & Design Principles
• Layered Architecture: separation of concerns between HTTP layer (routers), business logic (services), data layer (models).
• Dependency Injection: central in FastAPI via “Depends” for database sessions, settings, security.
• Configuration via environment variables (.env) and app/core/setting.py.
• Middleware for logging, security headers, CORS, etc.
• Database migrations managed by Alembic → versioned SQL scripts.