hamid
46 lines
2.7 KiB
Markdown
46 lines
2.7 KiB
Markdown
# 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.
|