For implementers picking deployment and developer tooling. Each row names a role, the current pick, and the trigger that would force a swap.
| Role |
Pick |
Why |
Swap trigger |
| Build backend |
hatchling |
Standard PEP 517, uv-friendly |
Workspace tool requiring different backend |
| Container image |
SHIPPED |
apps/api/Dockerfile; the build command and the three non-negotiable image facts are on the Deployment page |
Registry and orchestrator remain deferred |
| Runtime target |
Deferred (Kubernetes, Cloud Run, ECS, bare VMs) |
Not deployed beyond local dev |
First non-local deployment |
| Image registry |
Deferred (ghcr, Docker Hub) |
Tied to runtime-target pick |
Locked alongside runtime target |
| Role |
Pick |
Why |
| Package manager |
uv |
One fast tool replaces pip + virtualenv + pip-tools |
| Lint + format (Python) |
Ruff |
One tool, fast, growing rule coverage |
| Type checker |
Pyright (strict) |
Strictest available; structural typing aligns with Protocol ports |
| Test runner |
pytest + pytest-asyncio |
Python standard; --import-mode=importlib for src/ layout |
| HTTP test client |
httpx |
FastAPI's TestClient rides on it |
| Integration test isolation |
testcontainers (Postgres) |
Fresh Postgres per run; mirrors prod schema via Atlas |
| Import-boundary linter |
tach |
Enforces BC isolation at import time |
| Pre-commit |
pre-commit |
Hooks for lint, format, and type-check on commit |
| Local container runtime |
Docker + docker-compose |
Postgres + pgvector for local dev |
| CI |
GitHub Actions |
Repo on GitHub; standard |
| Docs site generator |
MkDocs Material |
Renders these docs, published to GitHub Pages. The version is pinned in exactly two places that must agree, .github/workflows/docs.yml and the MKDOCS variable in the Makefile; this row deliberately names no number, because a third copy is a third thing to drift |