conventions

CLAUDE.md - fastapi

Auto-generated by klaussy-repo-conventions. Customize and extend with project-specific context.

Project Overview

python project using fastapi.

FastAPI framework, high performance, easy to learn, fast to code, ready for production

Directory Structure

For the repository directory map and file layout, see .claude/directory-map.md.

Architecture

Core Modules

The most-imported internal modules — the foundation other code builds on.

• fastapi/exceptions.py — exceptions (12 dependents)
• fastapi/openapi/models.py — models (8 dependents)
• fastapi/types.py — types (8 dependents)
• fastapi/datastructures.py — datastructures (7 dependents)
• fastapi/utils.py — utils (5 dependents)
• fastapi/security/base.py — base (5 dependents)

Key Patterns

• API routes: 29 endpoints (2 DELETE, 16 GET, 2 PATCH, 7 POST, 2 PUT)

API Routes

• fastapi/applications.py: GET /users/, GET /items/, GET /items/, GET /items/, +4 more
• fastapi/background.py: POST /send-notification/{email}
• fastapi/datastructures.py: POST /files/, POST /uploadfile/
• fastapi/exceptions.py: GET /items/{item_id}
• fastapi/param_functions.py: GET /items/{item_id}, GET /items/, GET /users/me/items/
• fastapi/routing.py: GET /users/, GET /items/, PUT /items/{item_id}, POST /items/, +2 more
• security/api_key.py: GET /items/, GET /items/, GET /items/
• security/http.py: GET /users/me, GET /users/me, GET /users/me
• security/oauth2.py: POST /login, POST /login

Narrative: how the pieces fit together

FastAPI is a thin, typed layer on top of Starlette (ASGI toolkit, routing, middleware, responses) and Pydantic v2 (validation/serialization). It does not implement HTTP itself — it builds request handling around Starlette's Router/Route and delegates ASGI serving to Uvicorn (or any ASGI server) at runtime.

• fastapi/applications.py — the FastAPI class (class FastAPI(Starlette), ~4.7k lines). This is the top-level app object users instantiate; it owns OpenAPI schema generation/caching, exception handler registration, middleware setup, and delegates actual routing to an internal APIRouter.
• fastapi/routing.py — the biggest module (~6.4k lines). Defines APIRoute and APIRouter. This is where a decorated path operation function becomes an ASGI-callable: get_request_handler() builds the per-route closure that runs on every request, calling solve_dependencies() to resolve the dependency graph, then run_endpoint_function() to invoke the user's function (sync functions are offloaded to a threadpool via run_in_threadpool, async functions are awaited directly).
• fastapi/dependencies/utils.py + fastapi/dependencies/models.py — the dependency-injection engine. get_dependant() introspects a callable's signature (via inspect + type hints) to build a Dependant tree at route-registration time; solve_dependencies() walks that tree at request time, resolving path/query/header/cookie/body params, sub-dependencies, and security schemes, with results cached per-request via use_cache=True (default) on repeated sub-dependencies.
• fastapi/params.py / fastapi/param_functions.py — the Path, Query, Header, Cookie, Body, Form, File, Depends, Security marker classes and their public factory functions. These are what a user writes as default values (Annotated[X, Query(...)] style) that get_dependant() later parses back out.
• fastapi/_compat/ — the Pydantic version-compatibility shim (shared.py has the common helpers, v2.py has Pydantic-v2-specific code). This is the seam between FastAPI's internals and Pydantic's; the package layer is kept separate from callers even though only Pydantic v2 is supported now.
• fastapi/encoders.py — jsonable_encoder(), used to convert arbitrary Python/Pydantic return values into JSON-safe primitives before Starlette serializes the response.
• fastapi/openapi/ — models.py (Pydantic models mirroring the OpenAPI 3.1 spec), utils.py (walks all registered routes to build the schema dict), docs.py (serves Swagger UI / ReDoc HTML at /docs and /redoc).
• fastapi/security/ — OAuth2/API-key/HTTP-auth helper classes (OAuth2PasswordBearer, HTTPBasic, APIKeyHeader, etc.). Each is itself a callable Depends-compatible class that also injects an OpenAPI securitySchemes entry.
• fastapi/middleware/ — thin re-exports/wrappers around Starlette middleware (CORS, GZip, TrustedHost, WSGI bridge) plus asyncexitstack.py, which manages the request-scoped AsyncExitStack used to close yield-style dependencies.