Architecture Decision RecordsADR-0005: OpenAPI Contract-First

ADR-0005: OpenAPI Contract-First Development

Status

Accepted

Context

We need a single source of truth for API types shared between the Go backend and TypeScript frontend. Hand-writing types leads to drift, inconsistencies, and bugs at integration boundaries.

Decision

Use an OpenAPI 3.1 specification (/openapi.yaml) as the single source of truth. All API types, request/response schemas, and endpoint definitions are defined here first. Bi-directional codegen produces:

  • TypeScript types + openapi-fetch client (via openapi-typescript)
  • Go validation (via OpenAPI spec)

Every feature begins by modifying the OpenAPI contract.

Consequences

Positive

  • Single source of truth eliminates type drift between frontend and backend
  • Generated TypeScript client is always in sync with the API
  • API changes are reviewed at the contract level before implementation
  • OpenAPI spec serves as living API documentation

Negative

  • Extra step in the development workflow (contract → codegen → implementation)
  • OpenAPI 3.1 has a learning curve
  • Complex schemas can be verbose in YAML
ADR-0004: Temporal for Durable WorkOverview