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