Initial extracted documentation set

README.md

@@ -0,0 +1,73 @@
+# 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.