baya-monorepo/dev/contracts/README.md

Contracts — MOVED to docs/integration/

⛔ This folder is history. Do not read it as the contract.

The live client↔server contract is docs/integration/. Start at its index.md — the whole seam on one page — then open the one domain file you need.

Was here	Now
conventions/api-conventions.md + conventions/money-and-types.md	docs/integration/api-contract.md
domains/*.md (17 files, named after backend phases)	docs/integration/domains/ (22 files, named after the client's services/ domains)
openapi/swagger.v1.json (2026-07-13)	docs/integration/openapi/ (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.

Phase 6 archives this folder. Until then it stays readable as a record, not as an instruction.

---

The original README, kept for the record

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; 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.