> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sesameterminal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0002. OpenAPI 3.0.3 contract with generated Go and TypeScript code

# 0002. OpenAPI 3.0.3 contract with generated Go and TypeScript code

* **Status:** Accepted
* **Date:** 2026-09-30

## Context

The backend (Go) and frontend (TypeScript) are built by different agents at the same
time. Both sides need the same request, response and WebSocket message types. Types
written by hand on each side drift apart, and a mismatch in a price or size field can
place a wrong order.

## Decision

* `api/openapi.yaml` is the single source of truth for REST endpoints and WebSocket
  messages. WebSocket messages are defined as JSON Schema components in the same file.
* The spec uses **OpenAPI 3.0.3**, not 3.1, because `oapi-codegen` only partly supports
  3.1.
* `task gen` generates:
  * the Go strict server and types with `oapi-codegen` into
    `backend/internal/httpapi/gen`;
  * the TypeScript types with `openapi-typescript`, used through `openapi-fetch`, into
    `frontend/src/lib/api/gen`.
* Generated code is never edited by hand. To change a type, edit the spec and run
  `task gen`.
* Contract changes land in their own PR before the code that uses them. Each phase
  starts with the contract diff.
* Wire rules: snake\_case field names, RFC 3339 UTC timestamps, money, prices and sizes
  as decimal strings, never a bare `mode` field.

## Consequences

* Frontend and backend work in parallel against the same generated types from the start
  of a phase.
* A contract mismatch becomes a compile error on one side instead of a runtime bug.
* 3.1-only features are not available. Nullable fields use `nullable: true`, and JSON
  Schema keywords added in 3.1 cannot be used.
* The codegen tool versions must be pinned so that every machine generates the same
  code.
* Contract changes go through the tech lead, which adds a step to changes that touch
  both sides.

## Alternatives considered

* **OpenAPI 3.1.** Aligns with current JSON Schema, but `oapi-codegen` support is
  incomplete, so generated Go code would be unreliable.
* **Hand-written types on each side.** No tooling, but the two sides drift.
* **gRPC or Connect with protobuf.** Strong typing, but the browser needs an extra
  transport layer, and payloads are harder to inspect in browser dev tools.
* **Generate TypeScript from Go types.** Makes Go the source of truth and leaves no
  reviewable contract file for parallel work.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.