My API

FastAPI + SQLAlchemy async + Alembic + dependency-injector template.

Setup

# Install dependencies (creates .venv automatically)
uv sync

# Copy env file
cp .env.example .env.development

# Start local environment
docker compose up -d

# Run migrations
uv run alembic upgrade head

# Start API server
uv run uvicorn main_api:app --reload

Project Structure

├── alembic/                    # Database migrations (Alembic)
│   ├── versions/               # Migration scripts
│   ├── env.py                  # Alembic environment config
│   └── script.py.mako          # Migration file template
├── contracts/                  # Pydantic request/response DTOs
│   └── base.py                 # PaginationParams, PaginatedResponse
├── controllers/                # API route handlers
│   ├── base/                   # Shared controller utilities
│   │   └── auth.py             # Bearer token authentication
│   ├── health_controller.py    # Health check endpoints
│   └── v1/                     # Versioned API routes
├── core/                       # Application bootstrap
│   ├── config.py               # Pydantic settings (env-based)
│   ├── dependency_injection.py # DI container definition
│   └── logging.py              # Colored logging setup
├── database/                   # Database layer
│   ├── database.py             # Async SQLAlchemy engine & sessions
│   ├── init_database.py        # DB & schema creation utilities
│   ├── schema_base.py          # Declarative base for ORM models
│   └── seeds/                  # Seed data scripts
├── exceptions/                 # Custom exception hierarchy
│   ├── base.py                 # AppError base class
│   └── types.py                # NotFoundError, UnauthorizedError, etc.
├── mappers/                    # Model ↔ DTO transformations
├── middlewares/                 # FastAPI middleware
│   ├── exception_handling.py   # Maps exceptions to HTTP responses
│   ├── request_logging.py      # Request/response logging
│   └── validation_handling.py  # Pydantic validation error handler
├── repositories/               # Data access layer
│   ├── base_repository.py      # Generic async CRUD operations
│   ├── enums/                  # Database enum types
│   ├── models/                 # SQLAlchemy ORM models
│   └── views/                  # Database view models
├── scripts/                    # Utility scripts
├── services/                   # Business logic layer
│   └── filters/                # Query filter builders
├── templates/                  # Template files
│   └── email/                  # Email templates
├── tests/                      # Test suite
│   ├── conftest.py             # Global fixtures (DB, container)
│   ├── critical/               # Critical path tests (run first)
│   ├── database/               # Database layer tests
│   ├── factories/              # factory-boy test data factories
│   ├── integration/            # Integration tests
│   ├── logging/                # Logging config tests
│   ├── repositories/           # Repository tests
│   └── services/               # Service tests
├── worker/                     # Background job scheduler
│   ├── dependency_injection.py # Worker-specific DI container
│   ├── job_manager.py          # Job lifecycle management
│   ├── jobs/                   # Scheduled job implementations
│   └── scheduler_singleton.py  # APScheduler singleton
├── main_api.py                 # FastAPI application entry point
├── main_worker.py              # Background worker entry point
├── alembic.ini                 # Alembic configuration
├── docker-compose.yml          # PostgreSQL + API + Worker services
├── Dockerfile                  # Production container image
├── Dockerfile.local            # Development container image
├── pyproject.toml              # uv dependencies & tool config
├── uv.lock                     # uv resolved dependency lockfile
└── pytest.ini                  # Pytest configuration

Architecture

Controller (controllers/v1/) -> Service (services/) -> Repository (repositories/)
     |                              |                        |
  Contracts                      Mappers              SQLAlchemy Models
 (contracts/)                  (mappers/)          (repositories/models/)

Commands

# Run tests
uv run pytest

# Code quality
uv run black . && uv run ruff check --fix .

# Create migration
uv run alembic revision --autogenerate -m "description"

# Apply migrations
uv run alembic upgrade head