backend-fastapi-python

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](./references/file-structure.md) | | Settings and env vars | [configuration.md](./references/configuration.md) | | Database sessions and connections | [database.md](./references/database.md) | | ORM models | [models.md](./references/models.md) | | Request/response schemas | [schemas.md](./references/schemas.md) | | Router and endpoint patterns | [routing.md](./references/routing.md) | | Service layer patterns | [services.md](./references/services.md) | | Dependency injection | [dependencies.md](./references/dependencies.md) | | Middleware setup | [middleware.md](./references/middleware.md) | | Error handling | [error-handling.md](./references/error-handling.md) | | Auth flow example | [auth.md](./references/auth.md) |