FastAPI Production Rules

FastAPI Production Rules

A set of conventions, patterns, and hard rules for building production-grade FastAPI projects.

Structure

SKILL.md                               # all rules, short examples, checklists
references/
├── toolchain.md                       # uv, ruff, ty, pyproject.toml, CI
├── app-setup.md                       # settings, app factory, lifespan, middleware, CORS, OpenAPI
├── errors-and-responses.md            # exceptions, handlers, response wrappers, schemas, pagination
├── database.md                        # SQLAlchemy async, models, transactions, locking, Alembic
├── auth-and-security.md               # passwords, JWT, refresh tokens, magic links, roles, rate limits, uploads
├── logging-and-observability.md       # structlog, request context, Sentry, OpenTelemetry, health checks
├── background-tasks.md                # ArdiQ tasks, idempotency, retries, cron, outbox
├── api-patterns.md                    # idempotency keys, webhooks, streaming, outbound HTTP, SSRF, caching, audit
├── testing.md                         # testcontainers, fixtures, tenant-isolation and architecture tests
├── deployment.md                      # Dockerfile, uvicorn, migrations in the pipeline, probes
└── crud-example.md                    # a complete domain: model → schemas → service → router → tests

What it covers

• Toolchain: uv, ruff (including FastAPI-specific rules), ty, CI
• Project structure and app factory with lifespan
• Router → Service → Model separation
• One transaction per use case
• Dependency injection with Annotated
• Custom exceptions and one error format for every error
• Typed response wrappers and correct status codes
• Pydantic v2 schemas that prevent mass assignment
• Offset and cursor pagination with stable ordering
• Multi-tenancy and IDOR prevention
• SQLAlchemy 2.0 async: sessions, explicit loading, integrity, locking
• Zero-downtime Alembic migrations
• Configuration with pydantic-settings
• Structured logging with structlog and request IDs
• Auth: argon2, JWT, rotating refresh tokens with reuse detection, magic links
• Role-based authorization
• Rate limiting
• HTTP security: CORS, security headers, SSRF
• File upload validation
• Background tasks with ArdiQ: idempotency, retries, priorities, cron, transactional outbox
• Idempotency keys and webhooks
• Native SSE and JSON Lines streaming (FastAPI ≥ 0.135)
• Testing with real Postgres, tenant-isolation and architecture tests
• Health checks, Sentry, OpenTelemetry
• Docker and deployment
• Naming conventions
• FastAPI gotchas
• Security and code review checklists

Stack

Examples use PostgreSQL + SQLAlchemy 2.0 async + Pydantic v2 + ArdiQ + Redis, but every principle applies to any ORM or task queue.

Related

How I structure FastAPI projects in production — and why — the post explaining the reasoning behind these rules.

The Python Toolchain I Use in Production: uv, ruff, and ty - another post explaining why i use all the astral stack (uv, ruff and ty)