# Frontend → Backend requests (append-only)

The frontend lane appends here when it needs a contract that doesn't exist yet, finds a shape mismatch,
or needs a new field/filter/endpoint. The backend agent reads this at the start of each phase and
delivers fixes in its own change. **Frontend never edits backend code to "fix" a gap — it requests it.**

<!-- TEMPLATE — copy per request
## REQ-NNN — <short title> — filed by frontend-phase-N-bM — <YYYY-MM-DD>
- **Need:** <endpoint / field / filter / shape>
- **Why:** <which screen/flow needs it>
- **Proposed shape:** <JSON sketch, optional>
- **Status:** open | delivered in backend-phase-K
-->

## REQ-001 — Confirm response envelope, wire casing & pagination shape — filed by frontend-phase-0 — 2026-07-02
- **Need:** Authoritative confirmation of three things the frontend types depend on:
  1. **Envelope unwrapping.** The b0 swagger shows every response wrapped in `ApiResult`
     (`{ isSuccess, statusCode, message, requestId, data }`). The frontend's `clientFetch` currently
     returns the **raw body**, so domain `clientApi`s read the payload via `unwrap()` (`data`). Confirm this
     is the intended shape for all endpoints (i.e. payload always under `data`), so the pattern is correct
     before f1+ copy it.
  2. **Wire casing.** Observed swagger properties are **camelCase** (`isSuccess`, `serverTimeUtc`) — not the
     snake_case `api-conventions.md` implies for URL segments. Please confirm JSON body casing is camelCase
     (and, if so, we can note it in the convention doc), or state where it differs.
  3. **Pagination payload.** `api-conventions.md` says lists return `items` + `total` (+ `page`/`page_size`).
     Confirm the exact field names/casing on the wire (we've typed `Paginated<T>` as
     `{ items, total, page, pageSize }` in `client/src/lib/api/types.ts`).
- **Why:** These fix the shared `ApiEnvelope<T>`/`Paginated<T>` types and the `services/{domain}` reference
  pattern every later frontend phase inherits.
- **Proposed shape:** `{ isSuccess: boolean, statusCode: number, message?: string, requestId?: string, data?: T }`
  and `data: { items: T[], total: number, page: number, pageSize: number }` for lists.
- **Status:** open