How teamhide/fastapi-boilerplate works
Project Type and Purpose
• This is a backend microservice/API boilerplate built with FastAPI, designed around Domain-Driven Design (DDD) and Hexagonal (Ports & Adapters) architecture.
• Its primary responsibilities are user management (CRUD, DTOs, validation) and JWT-based authentication, plus background tasks via Celery, caching via Redis, and asynchronous database access via SQLAlchemy.
File Structure Analysis
• Top-level directories:
• app/ – contains bounded contexts “auth” and “user,” each broken into adapter (input/output), application, domain, and a container for DI.
• core/ – shared libraries: configuration, async DB session management, exceptions, FastAPI middlewares/dependencies, cache abstractions, repository base.
• celery_task/ – standalone module for asynchronous background jobs.
• migrations/ & alembic.ini – database schema versioning.
• docker/ – Docker Compose setup plus initial SQL.
• main.py & app/server.py – entrypoints to wire FastAPI, DI container, cache, event dispatcher.
• tests/ – coverage for all layers.
README Insights
• Confirms stack: FastAPI + async SQLAlchemy sessions, JWT auth, permission dependencies, Celery workers, event dispatcher, caching with configurable backends.
• Deployment: Docker Compose, Alembic migrations, Poetry, pre-commit formatting.
a. Presentation Layer
• FastAPI HTTP Server (main.py → app/server.py)
• Routers: /api/v1/auth and /api/v1/user
b. Adapter Layer (API)
• Input adapters: Pydantic request/response schemas and controllers in app/*/adapter/input/api/v1
• Output adapters: Persistence adapters (SQLAlchemy + generic repository adapters)
c. Application Layer
• Services (application/service/*.py) orchestrating use cases
• DTOs and exception handling
d. Domain Layer
• Entities (User, JWT claims)
• Value Objects (e.g., Location)
• UseCase interfaces and business rules
e. Infrastructure Layer
• Async SQLAlchemy session factory, Transactional decorator
• Cache manager and backends (Redis)
• Celery worker & tasks
• Event dispatcher
• Configuration loader, Docker deploy
f. External Systems
• PostgreSQL (or other RDBMS)
• Redis
• Celery Broker (e.g., RabbitMQ/Redis)
Interactions and Data Flows
• Client → FastAPI HTTP Server → Authentication Middleware (JWT decoding & permission check) → Router → Input Adapter → Application Service → Domain UseCase → Repository Port → Output Adapter → Async SQLAlchemy → Database
• Application Service may dispatch domain events to the event dispatcher → Celery tasks
• Caching decorator intercepts service calls → Redis GET/SET → return cached data or fallback to underlying DB call
• Alembic manages schema migrations on startup
• Docker Compose brings up DB, Redis, and Celery broker/workers
Architectural Patterns and Principles
• Hexagonal Architecture (Ports & Adapters): clear separation of inbound adapters (API) and outbound adapters (DB, cache).
• Layered DDD: Domain layer is pure business logic; Application layer orchestrates; Adapters handle I/O.
• Dependency Injection via container.py in each module.
• Asynchronous I/O across web, DB, and cache.
• Transactional decorator to manage commit/rollback automatically.
Essential Elements to Capture
• All FastAPI routers and middlewares (authentication, logging, SQLAlchemy injection).
• DI Container initialization and binding of services to adapters.
• Data transformations: DTOs ↔ Entities.
• Event dispatch: from application layer to Celery tasks.
• Caching: decorator intercept, key maker, backend flow.
• Database transactions: session_factory vs. global session.