How s3rius/fastapi-template works
Purpose and Entry Points
This is a Python-distributed Cookiecutter generator for configurable FastAPI services, not a service itself. Users invoke python -m fastapi_template or its CLI command; the generator collects options and renders a selected project shape. Entry paths: fastapi_template/__main__.py, fastapi_template/cli.py, fastapi_template/input_model.py.
Generation Pipeline
CLI flags and/or interactive input are validated into a generation model, then supplied to the Cookiecutter template. Template defaults and conditional feature selection are defined centrally in fastapi_template/template/cookiecutter.json; generation-time validation and cleanup run through fastapi_template/template/hooks/pre_gen_project.py and fastapi_template/template/hooks/post_gen_project.py. conditional_files.toml and replaceable_files.toml support pruning or rewriting artifacts based on selected capabilities.
Generated Service Bootstrap
A rendered project exposes an ASGI FastAPI application and module entry point, with optional Gunicorn process support. Application construction binds routing, middleware/instrumentation, settings, and startup/shutdown management. Primary paths: fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/__main__.py, fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/application.py, fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/lifespan.py.
API Boundary: REST or GraphQL
Generation chooses REST or GraphQL. REST centralizes endpoint registration and separates feature routers into schemas/views; GraphQL centralizes its router and composes query/mutation schemas with a request context. Example APIs cover echo, dummy persistence, users, broker publishing, Redis, monitoring, and self-hosted docs. Paths: fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/api/router.py, fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/gql/router.py, fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/gql/context.py.
Persistence Boundary
The generated app selects no database or one database/ORM integration. Data access is intentionally isolated into ORM-specific model and DAO packages, allowing API handlers to avoid direct storage mechanics. Supported paths demonstrate SQLAlchemy, Tortoise, Piccolo, Ormar, Beanie/MongoDB, and raw Psycopg patterns: .../{{cookiecutter.project_name}}/db_sa/dao/dummy_dao.py, .../{{cookiecutter.project_name}}/db_tortoise/config.py, .../{{cookiecutter.project_name}}/db_beanie/models/dummy_model.py. Optional migration artifacts are generated per ORM where supported.
Managed External Services
Optional Redis, RabbitMQ, Kafka, and NATS adapters provide dependency injection plus FastAPI lifespan-owned client connection/disconnection. API/GraphQL operations sit above these adapters rather than owning clients. Representative paths: .../{{cookiecutter.project_name}}/services/redis/lifespan.py, .../{{cookiecutter.project_name}}/services/rabbit/dependencies.py, .../{{cookiecutter.project_name}}/services/kafka/lifespan.py.
Runtime and Delivery
Generated projects target Python/FastAPI under Uvicorn, optionally Gunicorn, containerized with Docker Compose. Compose can provision service dependencies and an OpenTelemetry-oriented variant; optional Taskiq provides background task integration. Observability choices include Prometheus-compatible monitoring, Sentry, Loguru, and OpenTelemetry. Paths: fastapi_template/template/{{cookiecutter.project_name}}/Dockerfile, fastapi_template/template/{{cookiecutter.project_name}}/docker-compose.yml, fastapi_template/template/{{cookiecutter.project_name}}/deploy/docker-compose.otlp.yml.
Main entry points: application.py FastAPI application · gql/router.py GraphQL API · api/router.py REST API · cli.py CLI
Components 19
Generator package
Collects inputs and renders the selected FastAPI project shape.
- User invocation · Runs the module or installed CLI command.
fastapi_template/__main__.py - CLI · Collects flags or interactive answers.
fastapi_template/cli.py - Generation model · Validates generation options.
fastapi_template/input_model.py - Cookiecutter renderer · Renders the configured project template.
Cookiecutter template
Defines defaults, hooks, and conditional generated artifacts.
- Template defaults · Central feature defaults and selections.
fastapi_template/template/cookiecutter.json - Generation hooks · Validate before generation and clean up afterward.
fastapi_template/template/hooks/pre_gen_project.py - Conditional artifacts · Prunes or rewrites files for selected capabilities.
Generated service
Rendered application structure and optional integrations.
- Service entry point · Starts the rendered ASGI service.
fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/__main__.py - FastAPI application · Binds routes, settings, middleware, and lifecycle.
fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/application.py - Application lifespan · Owns startup and shutdown resources.
fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/lifespan.py - REST API · Registers endpoint routers, schemas, and views.
fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/api/router.py - GraphQL API · Composes query and mutation schemas.
fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/gql/router.py - GraphQL context · Supplies request-scoped GraphQL dependencies.
fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/gql/context.py - Persistence adapters · Optional ORM-specific models and DAOs isolate storage.
- External service adapters · Optional Redis and broker clients exposed through dependencies.
- Taskiq integration · Optional background task runtime.
Runtime and delivery
Processes and container deployment artifacts.
- Uvicorn / Gunicorn · Runs the generated ASGI application.
- Docker Compose · Runs the app and optional dependencies, including OTLP variant.
fastapi_template/template/{{cookiecutter.project_name}}/docker-compose.yml - Observability · Optional Prometheus, Sentry, Loguru, and OpenTelemetry.
fastapi_template/template/{{cookiecutter.project_name}}/deploy/docker-compose.otlp.yml
Connections 21
- User invocation → CLI: starts
- CLI → Generation model: validates options
- Generation model → Cookiecutter renderer: supplies context
- Template defaults → Cookiecutter renderer: defines defaults
- Generation hooks → Cookiecutter renderer: pre/post generation
- Conditional artifacts → Cookiecutter renderer: selects artifacts
- Cookiecutter renderer → Service entry point: renders
- Service entry point → FastAPI application: starts
- FastAPI application → Application lifespan: manages
- FastAPI application → REST API: REST option
- FastAPI application → GraphQL API: GraphQL option
- GraphQL API → GraphQL context: uses
- REST API → Persistence adapters: uses optional data access
- GraphQL API → Persistence adapters: uses optional data access
- Application lifespan → External service adapters: connects and disconnects
- REST API → External service adapters: uses dependencies
- GraphQL API → External service adapters: uses dependencies
- FastAPI application → Taskiq integration: optional integration
- Uvicorn / Gunicorn → FastAPI application: serves
- Docker Compose → Uvicorn / Gunicorn: runs
- Observability → FastAPI application: instruments