# s3rius/fastapi-template architecture

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

- Interactive diagram: https://gitdiagram.com/s3rius/fastapi-template
- Repository: https://github.com/s3rius/fastapi-template

## Overview

#### 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: [`fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/application.py`](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/application.py) (FastAPI application), [`fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/gql/router.py`](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/gql/router.py) (GraphQL API), [`fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/api/router.py`](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/api/router.py) (REST API), [`fastapi_template/cli.py`](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generator["Generator package"]
  node_invoke(("User invocation<br/>entry point<br/>[__main__.py]"))
  node_cli["CLI<br/>command interface<br/>[cli.py]"]
  node_input_model["Generation model<br/>validation model<br/>[input_model.py]"]
  node_cookiecutter{{"Cookiecutter renderer<br/>project renderer"}}
end

subgraph group_template["Cookiecutter template"]
  node_template_defaults["Template defaults<br/>Cookiecutter config<br/>[cookiecutter.json]"]
  node_generation_hooks["Generation hooks<br/>template hooks<br/>[pre_gen_project.py]"]
  node_conditional_artifacts["Conditional artifacts<br/>template rules"]
end

subgraph group_generated["Generated service"]
  node_service_entry["Service entry point<br/>Python module<br/>[__main__.py]"]
  node_application["FastAPI application<br/>ASGI bootstrap<br/>[application.py]"]
  node_lifespan["Application lifespan<br/>lifecycle manager<br/>[lifespan.py]"]
  node_rest_api["REST API<br/>router registry<br/>[router.py]"]
  node_graphql_api["GraphQL API<br/>GraphQL router<br/>[router.py]"]
  node_graphql_context["GraphQL context<br/>request context<br/>[context.py]"]
  node_persistence[("Persistence adapters<br/>ORM and database boundary")]
  node_service_adapters["External service adapters<br/>managed clients"]
  node_background_tasks["Taskiq integration<br/>background tasks"]
end

subgraph group_delivery["Runtime and delivery"]
  node_asgi_runtime{{"Uvicorn / Gunicorn<br/>process runtime"}}
  node_containers["Docker Compose<br/>container deployment<br/>[docker-compose.yml]"]
  node_observability["Observability<br/>instrumentation"]
end

node_invoke -->|"starts"| node_cli
node_cli -->|"validates options"| node_input_model
node_input_model -->|"supplies context"| node_cookiecutter
node_template_defaults -->|"defines defaults"| node_cookiecutter
node_generation_hooks -->|"pre/post generation"| node_cookiecutter
node_conditional_artifacts -->|"selects artifacts"| node_cookiecutter
node_cookiecutter -->|"renders"| node_service_entry
node_service_entry -->|"starts"| node_application
node_application -->|"manages"| node_lifespan
node_application -.->|"REST option"| node_rest_api
node_application -.->|"GraphQL option"| node_graphql_api
node_graphql_api -->|"uses"| node_graphql_context
node_rest_api -.->|"uses optional data access"| node_persistence
node_graphql_api -.->|"uses optional data access"| node_persistence
node_lifespan -->|"connects and disconnects"| node_service_adapters
node_rest_api -.->|"uses dependencies"| node_service_adapters
node_graphql_api -.->|"uses dependencies"| node_service_adapters
node_application -.->|"optional integration"| node_background_tasks
node_asgi_runtime -->|"serves"| node_application
node_containers -->|"runs"| node_asgi_runtime
node_observability -.->|"instruments"| node_application

click node_invoke "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/__main__.py"
click node_cli "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/cli.py"
click node_input_model "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/input_model.py"
click node_template_defaults "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/cookiecutter.json"
click node_generation_hooks "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/hooks/pre_gen_project.py"
click node_service_entry "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/__main__.py"
click node_application "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/application.py"
click node_lifespan "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/lifespan.py"
click node_rest_api "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/api/router.py"
click node_graphql_api "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/gql/router.py"
click node_graphql_context "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/gql/context.py"
click node_containers "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/docker-compose.yml"
click node_observability "https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/deploy/docker-compose.otlp.yml"

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_invoke,node_cli,node_input_model,node_cookiecutter toneBlue
class node_template_defaults,node_generation_hooks,node_conditional_artifacts toneAmber
class node_service_entry,node_application,node_lifespan,node_rest_api,node_graphql_api,node_graphql_context,node_persistence,node_service_adapters,node_background_tasks toneMint
class node_asgi_runtime,node_containers,node_observability toneRose
```

## Components

### Generator package

Collects inputs and renders the selected FastAPI project shape.

- [User invocation](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/__main__.py): entry point · Runs the module or installed CLI command. · `fastapi_template/__main__.py`
- [CLI](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/cli.py): command interface · Collects flags or interactive answers. · `fastapi_template/cli.py`
- [Generation model](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/input_model.py): validation model · Validates generation options. · `fastapi_template/input_model.py`
- **Cookiecutter renderer**: project renderer · Renders the configured project template.

### Cookiecutter template

Defines defaults, hooks, and conditional generated artifacts.

- [Template defaults](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/cookiecutter.json): Cookiecutter config · Central feature defaults and selections. · `fastapi_template/template/cookiecutter.json`
- [Generation hooks](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/hooks/pre_gen_project.py): template hooks · Validate before generation and clean up afterward. · `fastapi_template/template/hooks/pre_gen_project.py`
- **Conditional artifacts**: template rules · Prunes or rewrites files for selected capabilities.

### Generated service

Rendered application structure and optional integrations.

- [Service entry point](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/__main__.py): Python module · Starts the rendered ASGI service. · `fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/__main__.py`
- [FastAPI application](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/application.py): ASGI bootstrap · Binds routes, settings, middleware, and lifecycle. · `fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/application.py`
- [Application lifespan](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/lifespan.py): lifecycle manager · Owns startup and shutdown resources. · `fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/lifespan.py`
- [REST API](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/api/router.py): router registry · Registers endpoint routers, schemas, and views. · `fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/api/router.py`
- [GraphQL API](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/gql/router.py): GraphQL router · Composes query and mutation schemas. · `fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/gql/router.py`
- [GraphQL context](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/%7B%7Bcookiecutter.project_name%7D%7D/web/gql/context.py): request context · Supplies request-scoped GraphQL dependencies. · `fastapi_template/template/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}/web/gql/context.py`
- **Persistence adapters**: ORM and database boundary · Optional ORM-specific models and DAOs isolate storage.
- **External service adapters**: managed clients · Optional Redis and broker clients exposed through dependencies.
- **Taskiq integration**: background tasks · Optional background task runtime.

### Runtime and delivery

Processes and container deployment artifacts.

- **Uvicorn / Gunicorn**: process runtime · Runs the generated ASGI application.
- [Docker Compose](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/docker-compose.yml): container deployment · Runs the app and optional dependencies, including OTLP variant. · `fastapi_template/template/{{cookiecutter.project_name}}/docker-compose.yml`
- [Observability](https://github.com/s3rius/fastapi-template/blob/master/fastapi_template/template/%7B%7Bcookiecutter.project_name%7D%7D/deploy/docker-compose.otlp.yml): instrumentation · Optional Prometheus, Sentry, Loguru, and OpenTelemetry. · `fastapi_template/template/{{cookiecutter.project_name}}/deploy/docker-compose.otlp.yml`

## Connections

- 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