70-docs/60-decisions/ADR-015-openapi-typescript-codegen.md

ADR-015: REST API + openapi-typescript codegen

Status: Locked Date: 2026-05-13

Context

The Next.js frontend talks to the FastAPI backend over HTTP. Request/response types need to stay in sync as the backend evolves — manual TypeScript type maintenance always rots within weeks.

Decision

• REST transport layer (not GraphQL, not gRPC, not tRPC).
• FastAPI auto-generates OpenAPI 3.x schema (/openapi.json).
• openapi-typescript codegens TypeScript types into frontend/src/lib/api-types.ts on every build.
• frontend/src/lib/api.ts wraps fetch with typed helpers (postChat, postProfile, getCoverage, etc.).

Alternatives considered

Approach	Why rejected
Manual TypeScript types	Rot pattern is universal; types drift from backend reality within weeks.
GraphQL	Overkill for our REST-shaped data; adds resolver layer + N+1 risks; Sarvam ecosystem doesn't expect it.
tRPC	Node-only; doesn't fit our Python backend.
gRPC	Overkill; HTTP/2 dependencies + protobuf tooling adds friction.

Implementation

FastAPI (auto OpenAPI) → openapi-typescript → api-types.ts → typed fetch wrappers

Build hook: frontend/scripts/codegen.sh runs openapi-typescript http://localhost:7860/openapi.json -o src/lib/api-types.ts after every backend deploy.

Consequences

Positive:

• Single source of truth for API shape (the FastAPI Pydantic models).
• Type drift caught at TypeScript compile time.
• Refactors on the backend immediately surface as TypeScript errors on the frontend.
• No GraphQL N+1 trap.

Negative:

• Streaming responses require a parallel path (Server-Sent Events or WebSocket; not codegen-friendly).

Mitigations:

• For the streaming case (voice STT live), we keep a hand-written WebSocket handler.

Revisit at scale

v2: if real-time streaming (full-duplex voice) becomes the dominant pattern, add a WebSocket route alongside REST. Codegen for the REST half stays.