# Contracts — the shared interface between `client/` and `server/`

The two projects are independent (no shared build). This folder is their **single shared source of
truth** for everything that crosses the wire: API routes, request/response shapes, status codes, enums,
shared flows, and money/format conventions. It lets a frontend agent build against a stable contract
**before, during, and after** the matching backend phase, and it lets the two run in parallel.

## Ownership (this is what makes parallel work safe)

- **Backend owns and writes** `contracts/domains/*` and `contracts/openapi/*`. A backend phase that
  ships an API writes/updates the contract in the **same** change.
- **Frontend reads** contracts and derives its TypeScript types from them. The frontend never edits
  files here. If a contract is missing or wrong, the frontend appends a request to
  [`../shared-working-context/frontend/requests/for-backend.md`](../shared-working-context/frontend/requests/for-backend.md);
  the backend delivers the fix in a later change.

## What's here

| Path | What it is |
| --- | --- |
| `conventions/api-conventions.md` | The envelope, routing, pagination, errors, auth, locale — read first. |
| `conventions/money-and-types.md` | How money, dates, enums, gender, IDs are represented on the wire. |
| `domains/_TEMPLATE.md` | The shape every per-domain contract doc follows. |
| `domains/<domain>.md` | One file per domain (identity, catalog, booking, payments, …), added by the backend phase that ships it. |
| `openapi/` | The published `swagger.json` snapshot(s) — the machine-readable contract for type generation. |

## How a contract is produced (backend)

1. Build the endpoints following `server/CONVENTIONS.md`.
2. Write/extend `domains/<domain>.md` from `domains/_TEMPLATE.md`: every route, its method + snake_case
   path, auth/policy, request and response JSON (with a real example), the enums it uses, and the error
   cases. Reference, don't restate, `conventions/*`.
3. Publish the OpenAPI snapshot per `openapi/README.md`.
4. Note in your handoff (`shared-working-context/backend/handoff/after-backend-phase-N.md`) that the
   contract is live.

## How a contract is consumed (frontend)

1. Read `domains/<domain>.md` + `conventions/*`. Derive types in `src/services/{domain}/types.ts`
   (or generate from `openapi/swagger.json`) — keep names aligned with the contract.
2. If something is missing/ambiguous, request it (don't guess) and mock behind the `services/{domain}`
   seam meanwhile.

> Keep contracts **versioned by being honest**: when a shipped shape changes, update its `domains/*` doc
> and the OpenAPI snapshot in the same change, and call it out in the handoff so the frontend re-syncs.