Backend FastAPI Python

Project-specific conventions for FastAPI with SQLModel, pydantic-settings, and async SQLAlchemy.

Architecture Decisions

1. Services are stateless functions — Not classes. First param is db: AsyncSession.
2. Generic response wrapper — Always use ApiResponse[T] for consistency.
3. Dependencies chain — get_current_user -> require_auth -> require_admin.
4. Module-scoped config — Each module can have its own {module}_config.py.
5. Error codes for frontend — AppException(status, message, error_code).

Gotchas

• SQLModel Relationship() fields are NOT included in API responses by default. You must explicitly add them to model_config or use a separate response schema with those fields.
• AsyncSession.refresh() does not load relationships. After commit, re-query with .options(selectinload(...)) if you need related objects.
• Pydantic V2 uses model_validator not validator. The @validator decorator is V1 and will break silently or raise deprecation warnings.
• Depends() in FastAPI creates a NEW instance per request — don't store state in dependency return values expecting it to persist.
• Background tasks (BackgroundTasks) run AFTER the response is sent. If they fail, the client already got a 200. Use proper task queues (Celery, ARQ) for anything that must not silently fail.
• Alembic --autogenerate misses: table renames (generates drop+create), index changes on existing columns, and Enum type modifications in PostgreSQL. Always review generated migrations.
• async def endpoints block the event loop if you call sync I/O inside them. Use run_in_executor for sync libraries or define the endpoint as def (FastAPI runs sync endpoints in a threadpool).
• HTTPException from FastAPI and HTTPException from Starlette are different classes. Importing the wrong one causes middleware to miss exception handlers.
• SQLAlchemy's lazy="selectin" on relationships causes N+1 queries in async sessions. Use explicit selectinload() in queries instead.
• Optional[str] = None in query params makes the field optional. str = None also works but loses type information — prefer the explicit Optional form.
• When using response_model, FastAPI filters OUT any fields not in the model. If your response is missing data, check that the response model includes all fields, not just the ORM model.

References

| When you need... | Read | |------------------|------| | Directory layout | file-structure.md | | Settings and env vars | configuration.md | | Database sessions and connections | database.md | | ORM models | models.md | | Request/response schemas | schemas.md | | Router and endpoint patterns | routing.md | | Service layer patterns | services.md | | Dependency injection | dependencies.md | | Middleware setup | middleware.md | | Error handling | error-handling.md | | Auth flow example | auth.md |