← All templates

Pydantic models are the contract, async all the way, OpenAPI always current.

Constitution — FastAPI service

Version 1.0.0 · Ratified 2026-11-10

These principles hold for every spec, plan and task of the project. A spec may add rules; it never weakens these.

  1. Pydantic models are the contract. Every route declares Pydantic request models and a response_model. No route returns a bare dict or an ORM object, so fields that are not in the response model never leak.

  2. Async all the way. Async routes call only async drivers and clients (asyncpg, SQLAlchemy async sessions, httpx.AsyncClient). A blocking call such as requests or time.sleep inside an async def fails the review; unavoidable blocking code runs in a plain def route or a thread pool.

  3. OpenAPI always current. The OpenAPI document is generated from the code and checked into the repository; CI fails when the generated schema differs from the committed one. Every route has a summary and documented error responses.

  4. Dependencies for cross-cutting concerns. Database sessions, the current user, settings and permissions come from Depends. Routes never open their own connections, and tests replace dependencies with app.dependency_overrides.

  5. Typed settings. Configuration is a pydantic-settings class loaded once at startup. A missing or invalid variable stops the service before it accepts traffic.

  6. Errors with a shape. Domain errors are typed exceptions mapped by exception handlers to status codes and one error body shape. Raising HTTPException from domain code fails the review.

  7. Type-checked and tested. mypy or pyright runs in strict mode in CI, and every route has tests with httpx.AsyncClient against the app covering success and a validation error.