FastAPI Roadmap

Mirror of GUIDES/FastAPI/00-roadmap.md, the canonical copy — edit there first, then re-sync this file.

The ordered build plan for a FastAPI service: nine phases from a blank repo to a monitored production deployment. One phase at a time — no phase starts before the previous deliverable exists. Estimates assume one experienced developer; solo, double them.

The chapters are reference. This file is what actually moves the project forward.

Phase 0 — Spec (½–2 days)

Goal: a written definition of the API before any tooling.

One-paragraph service statement ("This API does [job] for [clients], unlike [alt]")
Resource inventory: nouns, their CRUD verbs, and auth requirements per endpoint
Data model draft: entities, IDs, relationships, ownership rules
Non-functional requirements: auth? realtime? file uploads? webhooks? multi-tenant?
Consumer contract decided: public API (versioning matters) vs internal (move fast)
Map the nouns to feature routers (06. Routers & app structure)

Deliverable: one page a stranger could build the OpenAPI skeleton from.

Read: 01.

Phase 1 — Foundation (1–2 days)

Goal: an empty but correct service: boots, type-checks, lints, CI green.

Python 3.13+ and uv installed; versions pinned (02)
uv init + deps added: fastapi, uvicorn, pydantic-settings, sqlalchemy, alembic, …
app/ skeleton created from templates/app-tree.txt
App factory with lifespan + typed settings from .env (templates/app.py, templates/config.py)
ruff + mypy wired (templates/pyproject.toml)
CI job on every PR: lint → typecheck → tests (15)
/healthz and /readyz endpoints answering (14)

Deliverable: uv run uvicorn serves an empty app that returns 200 on /healthz; CI green.

Read: 02, 06.

Phase 2 — Walking skeleton (2–4 days)

Goal: one thin slice of real value, end to end: route → validation → DB → response.

Postgres running (docker compose); async engine + session factory (templates/database.py, 08)
Alembic initialised; first migration for one entity (08)
Pydantic request/response schemas for that entity (04)
One feature delivered completely: router + service + repository (06)
Errors mapped to consistent JSON problem shape (07)
httpx tests for the slice, CI green (10)

Deliverable: a demoable API with one genuinely useful resource, covered by tests.

Read: 03, 04, 08.

Phase 3 — Core capabilities (1–2 weeks)

Goal: the machinery every later endpoint needs exists once, correctly.

Auth flow: register/login, Argon2 hashing, JWT issue + verify, refresh (templates/security.py, 09)
get_current_user dependency + role/ownership guards via DI (templates/deps.py, 05)
CORS, request-ID middleware, global exception handlers (07)
Background task pattern: notifications, emails, jobs (07)
Pagination/filtering convention applied to list endpoints (03)
Structured logging with request context propagated (14)

Deliverable: new endpoints become mostly composition — auth, validation, logging included.

Read: 05, 07, 09.

Phase 4 — Feature build-out (weeks, variable)

Goal: the remaining product features, each as a vertical slice.

Feature per slice, same internal layout: router → schemas → service → models
Realtime where needed: WebSockets or SSE with reconnect strategy (11)
File uploads / streaming responses if the product needs them (11)
Third-party integrations behind typed clients in the feature folder
Rate limiting and abuse controls on public endpoints (13)
OpenAPI reviewed as a consumer would see it (15)

Deliverable: feature-complete against the Phase 0 spec.

Phase 5 — Quality (3–5 days + ongoing)

Goal: confidence that change does not break things.

Unit tests on services and domain logic; schema tests on validators (10)
Endpoint tests with DI overrides and seeded DB per test (10)
Contract tests: OpenAPI snapshot diffed in CI (15)
Performance budget set and measured: p95 latency, RPS ceiling (12)
N+1 audit on every list endpoint; connection pooling verified (08, 12)
Async audit: no blocking calls on the event loop (11, 12)

Deliverable: green suite in CI + recorded performance numbers.

Phase 6 — Hardening (2–4 days)

Goal: safe to hand to strangers.

Security pass against 09. Authentication and the 81-checklist
Secrets out of the repo; .env.example documents every setting (02)
AuthZ matrix reviewed: every endpoint declares its requirement (09)
Structured logs scrubbed of tokens/PII; error tracker receiving events (14)
Timeouts, retries and circuit breakers on outbound calls (12)
Dependency vulnerability scan in CI (15)

Deliverable: a live health dashboard and a passed checklist.

Phase 7 — Release (2–5 days)

Goal: serving production traffic behind HTTPS.

Production Dockerfile: non-root, multi-stage, pinned base (templates/Dockerfile, 13)
Reverse proxy (Caddy/nginx) terminating TLS; uvicorn behind it (13)
Worker/scale decision made: processes vs replicas, not threads (13)
Migrations run as a release step, backward-compatible by policy (08)
Graceful shutdown rehearsed: SIGTERM drains in-flight requests (13)
Rollback rehearsed: previous image + migration down or forward-fix policy

Deliverable: 1.0 serving real traffic; rollback tested.

Phase 8 — Operate & iterate (forever, ~1 h/week)

Goal: the service gets better instead of older.

Weekly triage: error rates, p95 latency, slow endpoints, DB lock waits (14)
FastAPI/Pydantic/SQLAlchemy upgrades on a cadence (uv + Renovate) (15)
OpenAPI snapshots reviewed on breaking-change detector (15)
Quarterly: re-run the 81-checklist, revisit ADRs (15)

Rules that keep this roadmap honest

Walking skeleton before features. One thin end-to-end slice beats five half-built routers.
No phase skips. Tests after Phase 5 are cheap; tests retrofitted in Phase 7 are not.
Deliverables are binary. Each phase ends with something that exists or does not.
Cut scope, not structure. A smaller feature set in a sound codebase ships; the reverse rarely does.
Re-estimate at each phase boundary. The roadmap is a living document — update it as reality diverges.

← README · Guide home · 01. API architecture →