baya-monorepo/dev/contracts/README.md

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