FastAPI Template

Production-ready FastAPI template with Clean Architecture, multi-transport support (HTTP / NATS consumers / Taskiq scheduler), and first-class Claude Code integration — custom skills, architecture hooks, and a review agent that teach the AI how the codebase is structured.

A batteries-included starting point for building async Python services. Ships with the boring-but-important stuff already wired: Dishka DI across three transports, SQLAlchemy 2.0 async + Alembic, Pydantic v2 contracts, JWT auth, pagination, layered testing with testcontainers, and strict layer boundaries enforced by Claude Code hooks so the architecture stays clean as the project grows.

Highlights

• Clean Architecture + Hexagonal — strict inward dependencies (application/ → database/ is the only documented exception). The full ruleset lives in CLAUDE.md.
• Three transports, one composition root — HTTP (FastAPI + Granian), message consumers (FastStream over NATS), scheduled jobs (Taskiq over NATS JetStream). All share the same Dishka container built by entrypoints/container.py.
• RequestBus + UseCase pattern — every transport translates input into a Request, calls request_bus.send(), and unwraps a Result. Zero business logic in endpoints/subscribers/tasks. Paired with an EventBus for fire-and-forget domain events, both inheriting a shared Bus[M] Protocol.
• Audience-first HTTP routing — endpoints grouped by who can call them (public/, user/, admin/, internal/). Auth is wired once at the router level; it's structurally impossible to forget on individual endpoints.
• Strict/lenient pagination split — HTTP contract enforces 10 ≤ limit ≤ 200; internal callers can request unbounded fetches via limit=None.
• Layered testing — unit (mocks only), integration (testcontainers Postgres/Redis/NATS), e2e (full HTTP stack via httpx.AsyncClient + ASGITransport).
• Claude Code native — custom skills for usecase / endpoint / repository / migration / tests / api-client, pre-commit hooks that block layer violations and protected-path edits, an architecture review agent, and a CLAUDE.md that's the authoritative spec.

Tech stack

Quick start

1. Install dependencies

uv sync

2. Start dependencies (Postgres, Redis, NATS)

make docker-dev-up

3. Configure .env

Copy the example settings and fill in cipher keys / DB credentials (see src/settings/core.py for all fields):

cp .env.example .env

Required keys: DB_*, REDIS_*, NATS_*, CIPHER_* (ALGORITHM, SECRET_KEY, PUBLIC_KEY — for HS256 set SECRET_KEY == PUBLIC_KEY, ACCESS_TOKEN_EXPIRE_SECONDS, REFRESH_TOKEN_EXPIRE_SECONDS).

4. Run migrations

make upgrade

5. Start the services

# HTTP API (FastAPI + Granian)
make run-http
# or: uv run python -m src.entrypoints.http

# Message consumer (FastStream over NATS)
make run-consumers
# or: uv run faststream run src.entrypoints.consumers:app

# Scheduler (Taskiq)
make run-worker       # uv run taskiq worker src.entrypoints.tasks:broker
make run-scheduler    # uv run taskiq scheduler src.entrypoints.tasks:scheduler

Each transport has its own entry point under src/entrypoints/ and all three share the same Dishka container built by entrypoints/container.py::build_container(settings, *extras).

Project layout

src/
├── application/       USE CASES — transport-agnostic business logic
│   ├── common/        ports (Hasher, Cache, JWT, Bus, RequestBus, EventBus, Broker), bus implementations, exceptions, Request base, OffsetPagination
│   └── v1/            usecases, services, results, events, constants
│
├── infrastructure/    OUTBOUND ADAPTERS — Redis, Argon2, PyJWT, aiohttp, NATS brokers, logging
│
├── database/          PERSISTENCE — first-class layer (shared kernel)
│   ├── models/        SQLAlchemy ORM (inherit Base with .as_dict())
│   ├── repositories/  create/select/select_many/update/delete/exists/count/upsert — fixed vocabulary
│   ├── queries/       Query Object pattern for complex SQL
│   └── types/         OrderBy, Loads literals, TypedDict payloads
│
├── presentation/      INBOUND ADAPTER — FastAPI HTTP
│   └── http/v1/
│       ├── contracts/     Pydantic request/response schemas + strict OffsetPagination
│       ├── guards/        Authorization (JWT + role check)
│       └── endpoints/     audience-first: public/, user/, admin/, internal/
│
├── consumers/         INBOUND ADAPTER — FastStream (NATS subscribers)
├── tasks/             INBOUND ADAPTER — Taskiq (scheduled jobs)
│
├── entrypoints/       composition root: http.py, consumers.py, tasks.py, container.py
├── common/            leaf utilities (Dishka helpers, formatters, types)
└── settings/          Pydantic Settings

See CLAUDE.md for the full architecture spec — layer rules, DBGateway patterns, list endpoint shape, ORM→Result mapping, naming conventions.

Testing

Three layers, marked and parallelized via pytest-xdist:

uv run pytest tests/unit/           # no I/O, mocks/fakes only (~1s)
uv run pytest tests/integration/    # real Postgres/Redis/NATS via testcontainers
uv run pytest tests/e2e/            # full HTTP stack via httpx.AsyncClient + ASGITransport
uv run pytest                       # all of the above

Test infrastructure notes:

• tests/conftest.py spins up containers once per session, runs Alembic migrations in a sync context (migration env uses asyncio.run internally), creates a per-worker DB for xdist isolation.
• Each test runs inside an outer transaction that's rolled back on teardown — state stays clean with no explicit reset.
• E2E tests use httpx.AsyncClient + httpx.ASGITransport (not TestClient) to keep asyncpg connections on the same event loop as the app, avoiding the classic "attached to a different loop" trap.

Claude Code integration

This template is designed to be developed with an AI assistant, not in spite of one. The .claude/ directory ships opinionated configuration so Claude Code understands the codebase rules, enforces them automatically, and can scaffold new features consistently.

Skills (.claude/skills/)

Custom skills that kick in when Claude is working on a specific kind of file. Each skill is a self-contained SKILL.md with examples, anti-patterns, and checklists.

Hooks (.claude/hooks/)

Runtime guards that execute on every tool call. Claude is blocked before it can make an architectural or safety mistake.

Hooks live in .claude/settings.json — the repo-committed config. No machine-specific state.

Agents (.claude/agents/)

CLAUDE.md

The authoritative project spec that Claude Code reads as part of its context on every session. It documents:

• Layer dependency rules (with table and diagram)
• The database/ exception and when it applies
• DBGateway usage rules with the three canonical patterns (read / write / read-then-write) and the anti-pattern table
• Base.as_dict() vs model_validate(orm) — the lazy-load footgun explained
• Audience-first HTTP endpoint organization
• The five-parameter list endpoint shape with pagination, filter contracts, and loads
• Strict vs lenient OffsetPagination split (presentation vs application)
• OffsetResult.map() for Result → Contract conversion
• RequestBus + UseCase + Request + Result rules (plus EventBus and the Bus[M] parent Protocol)
• Naming conventions (single vs list, GET query vs POST data, OpenAPI tags)
• Adding-a-new-feature checklist

If a rule isn't in CLAUDE.md, it isn't a rule.

Makefile targets

make install                       # uv sync --all-groups
make upgrade                       # alembic upgrade head
make downgrade                     # alembic downgrade -1
make generate NAME="add_widget"    # alembic revision --autogenerate
make history                       # alembic history

make run-http                      # FastAPI + Granian
make run-consumers                 # FastStream (NATS)
make run-worker                    # Taskiq worker
make run-scheduler                 # Taskiq scheduler

make lint                          # ruff check
make format                        # ruff format + ruff check --fix
make typecheck                     # mypy --strict
make check                         # lint + typecheck
make test                          # all pytest
make test-unit / test-integration / test-e2e

make docker-dev-up                 # start dev containers (Postgres, Redis, NATS)
make docker-dev-down               # stop them
make docker-dev-rebuild            # down + build --no-cache

Adding a new feature

The canonical walkthrough is in CLAUDE.md. Summary:

1. Model — add to database/models/, run make generate NAME="add_widget", inspect the migration
2. Types — Create{Entity}Type, Update{Entity}Type, {Entity}Loads in database/types/
3. Repository — wrap BaseRepository, add verbs from the fixed vocabulary, return Result[T]
4. Gateway — add a property on DBGateway in database/psql/__init__.py
5. Result — {Entity}Result(Result) in application/v1/results/
6. Use case — Request + UseCase in one file under application/v1/usecases/{domain}/; map ORM → Result via {Entity}Result(**orm.as_dict())
7. Register — add to application/v1/usecases/__init__.py::setup_use_cases()
8. Contract — Pydantic request/response in presentation/http/v1/contracts/
9. Endpoint — pick the audience folder, follow the five-parameter shape for lists
10. Tests — unit + integration + e2e

If you're using Claude Code, the usecase / endpoint / repository / migration / tests skills will walk you through each step with the exact patterns — including the test-coverage scenarios that prevent the classic "returned 200 but the mutation silently dropped a field" gap.

License

Released under the MIT License — see the LICENSE file for the full text.