doluedu-fastapi-template/CLAUDE.md

FastAPI Best Practices

Project Structure

Organize by domain (src/auth/, src/posts/), not file type. Each domain has: router.py, schemas.py, models.py, service.py, dependencies.py, config.py, exceptions.py.

Async Routes

• async def → non-blocking I/O only
• def (sync) → blocking operations (runs in threadpool)
• CPU-intensive → offload to worker processes (Celery, multiprocessing)
• Sync SDK? Use run_in_threadpool from Starlette

Pydantic

• Use extensively: regex, enums, Field constraints, EmailStr
• Split BaseSettings per domain
• Create custom base model for app-wide serialization
• ValueError in schema → returns ValidationError to client

Dependencies

• Use for DB/service validations, not just DI
• Chain dependencies to avoid repetition
• Prefer async dependencies
• Dependencies are cached per request

Follow the REST

• Consistent path variable names enable dependency reuse
• /profiles/{profile_id} and /creators/{profile_id} can share valid_profile_id dependency

Database

• Explicit naming conventions for indexes/constraints
• lower_case_snake, singular table names
• SQL-first for joins and aggregations
• Aggregate nested JSON in DB, not Python

Migrations (Alembic)

• Keep migrations static and reversible
• Use descriptive slugs: 2022-08-24_post_content_idx.py

Testing

• Async test client from day 0 (httpx)