# Contracts — MOVED to `docs/integration/`

> ## ⛔ This folder is history. Do not read it as the contract.
>
> **The live client↔server contract is [`docs/integration/`](../../docs/integration/index.md).** Start at
> its [index.md](../../docs/integration/index.md) — the whole seam on one page — then open the one
> [domain file](../../docs/integration/domains/index.md) you need.
>
> | Was here | Now |
> | --- | --- |
> | `conventions/api-conventions.md` + `conventions/money-and-types.md` | [`docs/integration/api-contract.md`](../../docs/integration/api-contract.md) |
> | `domains/*.md` (17 files, named after backend phases) | [`docs/integration/domains/`](../../docs/integration/domains/index.md) (22 files, named after the client's `services/` domains) |
> | `openapi/swagger.v1.json` (2026-07-13) | [`docs/integration/openapi/`](../../docs/integration/openapi/README.md) (refreshed 2026-07-29) |
>
> Everything here was **frozen 2026-07-13** and has been superseded. It was audited against the live
> swagger during phase 2: the route-level content held up (no route named here is missing from the live
> API), but the body-casing rule, the server's local URL scheme, the envelope's field count and the enum
> vocabularies had all drifted. What changed and why:
> [domains/index.md § What replaced what](../../docs/integration/domains/index.md#what-replaced-what).
>
> Phase 6 archives this folder. Until then it stays readable **as a record**, not as an instruction.

---

<details>
<summary>The original README, kept for the record</summary>

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.

</details>