Fastapi Backend Overview

FastAPI Backend Stack - Overview & Guidelines

Architecture Overview

This stack follows a 3-layer architecture with strict separation of concerns:

Router (API Layer) → Service (Business Logic) → Repository (Data Access) → Database

Layer Responsibilities

Project Structure (Entity-Based)

project/
├── pyproject.toml
├── .env.example
├── .python-version              # 3.12
├── ruff.toml
├── alembic.ini
├── alembic/
│   ├── env.py
│   ├── script.py.mako
│   └── versions/
├── src/
│   └── app/
│       ├── __init__.py
│       ├── main.py              # App factory
│       ├── config.py            # pydantic-settings
│       ├── database.py          # Async SQLAlchemy
│       ├── dependencies.py      # Shared dependencies (get_db)
│       ├── exceptions.py        # Custom exceptions
│       ├── exception_handlers.py
│       ├── logging.py           # Structured logging
│       ├── middleware/
│       │   ├── __init__.py
│       │   └── correlation_id.py
│       ├── core/                # Abstract base classes
│       │   ├── __init__.py
│       │   ├── models.py        # Base model, mixins
│       │   ├── schemas.py       # Base schemas
│       │   ├── repository.py    # AbstractRepository
│       │   └── service.py       # BaseService
│       ├── common/
│       │   ├── __init__.py
│       │   └── postgres_repository.py
│       ├── api/
│       │   ├── __init__.py
│       │   └── v1/
│       │       ├── __init__.py
│       │       └── router.py
│       └── {entity}/            # Per-entity folders
│           ├── __init__.py
│           ├── models.py
│           ├── schemas.py
│           ├── repository.py
│           ├── service.py
│           ├── router.py
│           ├── dependencies.py
│           └── filters.py
└── tests/
    ├── __init__.py
    ├── conftest.py
    └── api/v1/

Core Technologies

• Python: 3.12+
• Package Manager: uv (required)
• Framework: FastAPI
• ORM: SQLAlchemy 2.0+ (async)
• Database: PostgreSQL with asyncpg
• Validation: Pydantic v2
• Configuration: pydantic-settings
• Migrations: Alembic (async)
• Pagination: fastapi-pagination
• Filtering: fastapi-filter
• Linting: ruff

Key Design Decisions

1. UUID Primary Keys

All models use UUID primary keys for distributed system compatibility.

2. UTC Timestamps

All timestamps are timezone-aware UTC using DateTime(timezone=True).

3. Soft Delete

Models support soft delete via deleted_at timestamp. Queries automatically filter deleted records.

4. Entity-Based Organization

Each entity (e.g., items, users) has its own folder containing all related files.

5. Generic Repository Pattern

Type-safe repositories using Python generics: Repository[ModelType, CreateSchema, UpdateSchema]

6. PostgreSQL-Specific Features

Bulk operations use PostgreSQL's ON CONFLICT for upserts.

Data Flow

Request
  ↓
Middleware (Correlation ID)
  ↓
Router
  ├── Validates request (Pydantic)
  ├── Extracts filter params (fastapi-filter)
  └── Calls Service
        ↓
      Service
        ├── Applies business logic
        └── Calls Repository
              ↓
            Repository
              ├── Executes SQL (SQLAlchemy)
              └── Returns model instances
              ↑
            Database

Error Handling

All errors return a consistent JSON structure:

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND",
  "correlation_id": "uuid",
  "timestamp": "2025-01-05T12:00:00Z"
}

Available Skills

Load specific skills for detailed implementation:

Best Practices

1. SQL Only in Repositories: Never write SQLAlchemy queries outside repository layer
2. Type Everything: Use type hints everywhere, enable strict mypy
3. Async All The Way: Use async/await consistently
4. Dependency Injection: Use FastAPI's Depends() for all dependencies
5. Validate Early: Use Pydantic schemas at API boundary
6. Log with Context: Always include correlation_id in logs
7. Handle Errors Gracefully: Use custom exceptions, never raise generic ones

Converted and distributed by TomeVault — claim your Tome and manage your conversions.