fastapi-architectlisted
Install: claude install-skill ralvarez-ai/ralvaskills
# FastAPI Architecture
Targets **FastAPI 0.136** on **Python 3.14**. Companion to [python-architect](../../languages/python-architect/SKILL.md) and [sql-architect](../../databases/sql-architect/SKILL.md) (data access via `psycopg + .sql files`). Implementation skeletons in [RECIPES.md](RECIPES.md); pinned deps in [STACK.md](STACK.md).
## 1. Project structure — feature-based
One folder per bounded context. Each feature owns its router, service, repo, schemas, and SQL files. Full tree in [RECIPES.md](RECIPES.md).
- **`router.py`** depends on `service.py`; never reaches into `repo.py` directly.
- **`service.py`** is pure Python — no FastAPI imports. Easy to unit-test.
- **`schemas.py`** holds Pydantic models — never reused as ORM models or DB rows.
- **Keep the feature folder scannable, not minimal.** Split on a real responsibility seam, not to hit a file count; many cohesive modules in one feature folder are fine. See [code-design-refactor §4](../../refactoring/code-design-refactor/SKILL.md#4-extract).
## 2. Routing & versioning
- **URL-prefix versioning:** `/v1/users`, `/v1/orders`. Mount each version's routers under a `v1_router = APIRouter(prefix="/v1")`. Deprecate by mounting `/v2` alongside, never by mutating `/v1`.
- **One `APIRouter` per feature**, included in `main.py`.
- **Tags** match feature folder names (`tags=["users"]`) — drives OpenAPI grouping.
- **Path parameter types in the signature** (`user_id: UUID`) — FastAPI validates and parses for free.
- **Respon