Derive the frontend's API types from the backend's OpenAPI schema

[albertotb]

The "anything better to automate the contract" question, implemented. FastAPI already knows the whole contract, so this stops restating it by hand.

How it works

make generate-types dumps the schema without booting a server and runs openapi-typescript over it:

cd backend && uv run python -c "import json; from app.api import app; print(json.dumps(app.openapi()))" > ../frontend/openapi.json
npm --prefix frontend run generate-types   # -> src/api/schema.d.ts (committed)

src/api/backend.ts then reads its types out of that file instead of declaring them:

export type PredictBody = Body<paths['/predict']['post']>
export type PredictResponse = Ok<paths['/predict']['post']>

The hand-mirrored interface PredictResponse { output: number } is gone — that type now comes from the backend's Pydantic model, keyed by the endpoint path, so renaming the route breaks compilation too.

The gate

Contract regenerates and fails if the committed types differ. It checks git status, not git diff — the latter ignores an untracked or deleted file and passes vacuously, which is exactly what happened on my first attempt (the check said "no drift" while tsc was already failing).

Proof it earns its keep

I simulated a sync renaming Response.output → .result:

Layer	Before this PR	After
Contract drift check	n/a	❌ schema.d.ts is stale + diff
tsc / build	passed silently	❌ Property 'output' does not exist on type '{ result: number; }'
runtime curl assertion	❌ (only because we hardcoded .output == 5)	❌ unchanged

The difference: the curl assertion only catches changes to the three endpoints someone remembered to assert; the types catch any endpoint, parameter or field the frontend touches.

Scope, deliberately

Types-only rather than a generated client (tiangolo's template generates a full SDK with @hey-api/openapi-ts). One generated file, and the hand-written wrappers stay readable — a template should show the pattern, not hide it. If you'd rather have the full SDK later, hey-api also has a TanStack Query plugin that would fit this stack.

Existing checks untouched: types prove shape, not that the server answers (Contract's runtime assertions) and not that nginx strips /api (Docker). Structural / behavioural / infrastructural, one job each. Slimming the runtime assertions is possible now but I kept them so this PR only adds coverage.

Costs, honestly: one generated file committed (inherited by projects made from the template), a make generate-types step to remember locally (the gate catches forgetting), and Contract now installs node as well as uv (~15s).

🤖 Generated with Claude Code

https://claude.ai/code/session_011texLkDBELWbXsBf6San3M

---

Generated by Claude Code