backend-repo-architecturelisted

# Backend Repository Architecture A canonical backend archetype for Python/FastAPI services, derived from real-world production systems. ## When to use - Scaffolding a new FastAPI backend service - Reorganizing an existing backend to match team conventions - Understanding the standard service layout and responsibilities - Choosing between flat vs versioned domain layouts - Setting up multi-mode deployment (server + workers + consumers) - Implementing the standard config/connection/routing patterns ## Core conventions All conventions below are derived from production Python/FastAPI services: - **Reference service A** (cleanest reference, server-only, SQLAlchemy 2.0, versioned domains) - **Reference service B** (largest ~48 domain modules, flat layout, MODE dispatcher) - **Reference service C** (monorepo: apps/ + packages/, MODE dispatcher) - **Reference service D** (multi-deployment: SERVER_TYPE router gating, MODE dispatcher) **Entrypoint dispatcher** (used by services B, C, D): - `entrypoint.py` at repo root dispatches on `MODE` environment variable - Supported modes: `server`, `consumer`, `temporal_worker`, `worker`, `cron`, `webhook_server` - `server` mode runs `uvicorn app.application:get_app --factory=True` - Worker/consumer modes call `asyncio.run(service_main())` on the respective service module - Each mode may initialize metrics/telemetry before dispatching - **Note**: Service A is server-only (no entrypoint.py, Dockerfile runs gunicorn directly) **Application