hamid
73 lines
4.2 KiB
Markdown
73 lines
4.2 KiB
Markdown
# 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>
|