[Service Name]

A single-purpose FastAPI service. Async by default. Postgres for state. Dockerized.

Source of truth

Production runs as a container on Fly or Railway. The Dockerfile + locked requirements.txt define what runs. Local mirrors via docker compose up.

Tech stack

Python 3.13 + FastAPI 0.115 + Uvicorn. Pydantic v2 for request and response schemas. SQLAlchemy 2.x with the async API. Alembic for migrations. structlog for JSON logs. pytest + httpx for tests (real ASGI calls, no test client wrapping). uv for dependency management (way faster than pip).

Deploy

Build the Docker image, push to Fly or Railway. Health check at /healthz. Graceful shutdown via SIGTERM (FastAPI handles it).

File map

• app/main.py FastAPI app + route mounting
• app/api/ routers, one per resource
• app/schemas/ Pydantic models (request, response)
• app/models/ SQLAlchemy ORM models
• app/db.py engine + session factory
• app/deps.py reusable dependencies (auth, db session)
• app/settings.py Pydantic Settings (env loading)
• alembic/ migration history
• tests/ pytest specs
• Dockerfile slim Python image, multi-stage

.env keys

• DATABASE_URL postgresql+asyncpg://...
• API_KEY shared secret for inbound auth (if no JWT)
• LOG_LEVEL
• SENTRY_DSN optional

Hard rules

• Every endpoint declares response_model. No untyped JSON dicts.
• DB sessions via FastAPI Depends. Never instantiate AsyncSession in a handler.
• Migrations via Alembic auto-generate + manual review. Never edit applied migrations.
• Settings via Pydantic Settings class. No os.environ.get in business code.
• pytest runs against a throwaway Postgres in CI. No mocks for the DB layer.
• All structured logs include request_id set in middleware.

Recent significant changes

• 2026-05-06: Scaffolded. Locked: Pydantic v2 (faster), SQLAlchemy 2.x async (not Tortoise), uv (not poetry).

Next session: start here

1. uv venv && uv sync to install.
2. Create Postgres locally with docker compose up db.
3. alembic upgrade head to apply schema.
4. uvicorn app.main:app --reload.
5. Test /healthz, then implement the first business route.