# Integration — the client↔server seam

> **Populated by phase 2 — not yet written**, except the OpenAPI snapshot, which phase 0 refreshed.
> Until then the contract lives in [dev/contracts/](../../dev/contracts/README.md) (frozen 2026-07-13)
> and the deployment shape in [DEPLOY.md](../../DEPLOY.md).

The two projects have no shared build. Everything that crosses between them — envelope shape, casing,
pagination, idempotency, cookies and refresh, CORS, `NEXT_PUBLIC_API_URL`, three containers behind Caddy,
a remote SQL Server and the OTP relay — is described **here, as one thing**. Today it is described
nowhere as one thing, which is the gap this section closes.

## Planned contents

| File | Covers |
| --- | --- |
| `api-contract.md` | Envelope, casing, pagination, error shape, idempotency, auth headers/cookies |
| `domains/` | One file per service domain, refreshed against the live swagger |
| [`openapi/`](openapi/README.md) | The machine contract — **snapshot is current as of 2026-07-29** |
| `config-matrix.md` | Every env var and appsettings key: client, server, docker, the bot |
| `topology.md` | The runtime dependency graph — 3 containers + Caddy + remote SQL + OTP relay |

## What phase 0 already established

The machine contract barely drifted. Between the 2026-07-13 snapshot and the live server on 2026-07-29:
**one endpoint added** (`POST /api/v1/webhooks/payouts/{provider}`), **one schema changed**
(`GeneratePayoutBatchCommand`), nothing removed. Full diff in
[_plan/open-contradictions.md § OpenAPI drift](../_plan/open-contradictions.md#openapi-drift).

So phase 2's real work is the **17 hand-written** `dev/contracts/domains/*.md` files, which were frozen
the same day and have never been checked against anything mechanically — not the JSON.

Also open for this section: **C-2** (`SET_VIA_USER_SECRETS_OR_ENV` names a store that was removed),
**C-3** (`https://localhost:5002` in 18 places vs `http://` in `launchSettings.json`), **C-8** (two
contract files for messaging), **C-9** (a `v1.1` OpenAPI document that may not exist).