# FastAPI Conventions

**Descriptive first, prescriptive second.** This repo captures how mature FastAPI-adjacent codebases structure web services, then distills the conventions worth following.

Use this repo for framework and service-boundary concerns that do **not** belong in a language-level Python patterns repo.

## Structure

- `patterns/` — route, dependency, schema, persistence, error, and testing conventions
- `comparison/` — where FastAPI conventions differ from broader Python patterns
- `sources/` — upstream notes, code excerpts, and rationale
- `PROCESS.md` — the repeatable extraction/refinement workflow used to build this repo

## Current source base

Primary upstreams mined so far:
- `fastapi/fastapi`
- `encode/starlette`
- `pydantic/pydantic`
- `encode/httpx`
- `fastapi-users/fastapi-users`
- `fastapi/full-stack-fastapi-template`

Why this mix works:
- FastAPI: router composition, dependencies, semantic exceptions, override-based testing seams
- Starlette: lifespan, middleware, exception-layer mechanics, application assembly
- Pydantic: request/response model boundaries and validation/serialization caveats
- HTTPX: ASGI and transport-based testing seams
- FastAPI Users: dependency-driven auth and router factory patterns
- Full-stack FastAPI Template: real service module structure, session/auth wiring, and schema transitions

## Current convention set

- `patterns/routes.md`
- `patterns/dependencies.md`
- `patterns/pydantic-boundaries.md`
- `patterns/errors.md`
- `patterns/persistence.md`
- `patterns/testing.md`
- `comparison/fastapi-vs-python.md`

## What belongs here

Examples:
- thin route handlers vs embedded business logic
- request/response schema boundaries
- dependency injection shape and lifetime
- error envelope and exception translation
- app startup/shutdown and resource wiring
- sync/async boundaries at the HTTP layer

## What does **not** belong here

Do not duplicate generic Python rules unless FastAPI deliberately bends them. Link back to `python-patterns` instead.

## Reviewing this repo

Recommended review order:
1. `README.md`
2. `PROCESS.md`
3. `sources/*.md` for evidence quality
4. `patterns/*.md` for synthesis quality
5. `comparison/*.md` for split-of-concerns clarity

Questions to ask during review:
- Is the guidance actually FastAPI/service-boundary specific?
- Are framework seams described where the framework really owns behavior?
- Are testing and dependency claims grounded in real source and tests?
- Are caveats preserved instead of over-generalized?

## Core rule

Do not write convention docs from memory. First collect repeated upstream examples with `file:line` citations, then synthesize the convention.