Base Template

Note: This is a work-in-progress template. It demonstrates the architectural patterns but is not production-ready. Known gaps: no Alembic migration for the account table, no integration tests, ExternalServiceClient uses a placeholder API format, and CreateAccountCommand handler is not wired to any endpoint yet.

FastAPI service template built with Clean Architecture, DDD, CQRS, and the Mediator pattern.

Stack

• Python 3.11+, FastAPI, SQLAlchemy 2.0 (async), PostgreSQL
• Punq — dependency injection
• Structlog — structured logging
• pytest + pytest-asyncio — testing

Architecture

src/
├── domain/          # Business logic — entities, value objects, domain exceptions
├── application/     # Use cases — commands, queries, DTOs, interfaces
├── infrastructure/  # Framework code — DB, DI container, mediator, external clients
└── presentation/    # HTTP layer — FastAPI routes and schemas

Layers depend inward only: presentation → application → domain. Infrastructure implements interfaces defined in the application layer.

Quick Start

cp .env.example .env
docker compose -f deploy/compose/postgres.yaml up -d
poetry install
poetry run uvicorn presentation.api.main:app --host 0.0.0.0 --port 8000

API docs: http://localhost:8000/api/docs

Running Tests

poetry install --with dev
pytest tests/ -v

How to Use This Template

1. Rename account to your domain (e.g. user, order, product) across domain/, application/, infrastructure/, and presentation/
2. Replace ExternalServiceClient with your own external service implementation
3. Update EXTERNAL_SERVICE_URL in .env
4. Create a new Alembic migration for your table

API

Method	Path	Description
GET	/account/list	List all accounts (paginated)
POST	/account/	Fetch account info from external service
GET	/healthcheck	Health check