create mvp path

archive/docs/integration/domains/index.md

@@ -0,0 +1,121 @@
+# Domain contracts
+
+One file per client `services/` domain — **22 files, 22 domains, one-to-one.** Each names every server
+endpoint that belongs to it, verdicted against the live swagger and the real client code.
+
+> Last verified: 2026-07-30 against commit `d3ec723` and
+> [`../openapi/swagger.v1.json`](../openapi/swagger.v1.json) (2026-07-29).
+
+Read [`../api-contract.md`](../api-contract.md) first — the envelope, casing, pagination, errors, auth,
+idempotency and money rules hold everywhere and are not restated per domain.
+
+---
+
+## How to read a domain file
+
+Every endpoint carries one verdict:
+
+| Verdict | Means |
+| --- | --- |
+| **wired** | In swagger **and** called by the domain's real `apis/clientApi.ts` |
+| **unwired** | In swagger, no real client caller. Server-only, admin-only, or superseded — the reason is given |
+| **phantom** | The client calls it; **the server has no such route.** It 404s. Always carries its REQ |
+
+`phantom` rows are the frontend's proposed routes, filed as REQs and mocked behind the domain seam
+meanwhile. They are not bugs in the client — they are the contract's open edge — but on a domain whose
+mock is **off** they are live 404s, and that is called out where it happens.
+
+## The census
+
+186 operations, each in exactly one file below. 184 belong to a domain; 2 (`ping`) are platform
+endpoints and live in [`../api-contract.md`](../api-contract.md#platform-endpoints-outside-every-domain).
+
+| Domain file | `client/src/services/` | Seam | Server ops | Phantom |
+| --- | --- | --- | --- | --- |
+| [addresses.md](addresses.md) | `addresses` | real | 5 | — |
+| [admin.md](admin.md) | `admin` | **mock** | 14 | 5 |
+| [auth.md](auth.md) | `auth` | real | 7 | — |
+| [bnpl.md](bnpl.md) | `bnpl` | **mock** | 9 | 3 |
+| [booking-requests.md](booking-requests.md) | `bookingRequests` | real | 7 | — |
+| [bookings.md](bookings.md) | `bookings` | real | 16 | — |
+| [catalog.md](catalog.md) | `catalog` | real | 14 | — |
+| [geography.md](geography.md) | `geography` | real | 13 | — |
+| [notifications.md](notifications.md) | `notifications` | real | 4 | — |
+| [nurse.md](nurse.md) | `nurse` | real | 4 | — |
+| [partner-center.md](partner-center.md) | `partnerCenter` | **mock** | 9 | 6 |
+| [patient-records.md](patient-records.md) | `patientRecords` | **mock** | 5 | — |
+| [patients.md](patients.md) | `patients` | real | 5 | — |
+| [payment.md](payment.md) | `payment` | real | 3 | 1 |
+| [payouts.md](payouts.md) | `payouts` | **mock** | 13 | 1 |
+| [profiles.md](profiles.md) | `profiles` | real | 7 | — |
+| [refunds.md](refunds.md) | `refunds` | **mock** | 8 | 4 |
+| [reviews.md](reviews.md) | `reviews` | real | 8 | — |
+| [search.md](search.md) | `search` | real | 2 | — |
+| [service-areas.md](service-areas.md) | `serviceAreas` | real | 3 | — |
+| [tickets.md](tickets.md) | `tickets` | real | 11 | 1 |
+| [verification.md](verification.md) | `verification` | **mock** | 17 | 3 |
+| | | | **184** | **24** |
+
+"Seam" is the domain's `constants.ts` flag (`USE_<DOMAIN>_MOCK`): **15 real, 7 mock.** A mocked domain
+still has a complete real client — flipping the flag is one line in `apis/index.ts`.
+
+**Two phantoms sit on a domain whose mock is off**, so they are reachable and they 404:
+`GET /api/v1/bookings/payment_history` ([payment.md](payment.md), REQ-047) and
+`POST /api/v1/tickets/{id}/assign` ([tickets.md](tickets.md), REQ-063). Both are guarded in the client —
+the first renders an empty state, the second is behind a default-off capability flag.
+
+## Route-shape exceptions
+
+The routing convention is snake_case segments generated from `[controller]`/`[action]` tokens. **Four
+controllers hardcode a route string instead**, and three of those introduce hyphens:
+
+| Route | Controller | Note |
+| --- | --- | --- |
+| `api/v1/admin/partner-centers` | `AdminPartnerCentersController` | hyphens **and** a nested `admin/` segment; children add `/set-active`, `/sponsor-nurse` |
+| `api/v1/admin/tickets` | `AdminTicketsController` | nested `admin/` segment |
+| `api/v1/admin/reviews/moderation_queue` | `AdminReviewsController` | nested `admin/`, then snake_case |
+| `api/v1/internal/bookings/{bookingId}/center` | `InternalCentersController` | an `internal/` namespace |
+
+Every other admin controller uses a flat `admin_*` prefix (`admin_geo`, `admin_catalog`, `admin_refunds`,
+…). The split is historical, not meaningful. Since the route also derives the dynamic-permission key,
+normalising it is a breaking change to permissions as well as URLs — it is recorded here, not fixed.
+
+## Enum vocabularies
+
+Swagger declares **no** string enums (see
+[`../api-contract.md`](../api-contract.md#enums)), so each domain file carries its own vocabulary. Every
+one was cross-checked against the server's `Baya.Domain` code set **and** the client's string-literal
+union. All match except one, noted in [tickets.md](tickets.md).
+
+| Vocabulary | Domain file | Server source |
+| --- | --- | --- |
+| `BookingRequestStatus` · `RequiredCaregiverGender` | [booking-requests.md](booking-requests.md) | `Entities/Booking/BookingRequestStatus.cs` |
+| `BookingStatus` · `BookingSessionStatus` · `VisitVerificationStatus` | [bookings.md](bookings.md) | `Entities/Booking/*.cs` |
+| `PriceUnit` | [catalog.md](catalog.md) | catalog config rows |
+| `BnplStatus` · `BnplEligibilityStatus` · `ProviderCode` | [bnpl.md](bnpl.md) | `Entities/Bnpl/*.cs` |
+| `PaymentTransactionStatus` · `MoadianStatus` | [payment.md](payment.md) | `Entities/Payments/`, `Entities/Invoices/` |
+| `RefundStatus` · `RefundChannel` · `ClawbackStatus` · cancellation codes | [refunds.md](refunds.md) | `Entities/Refunds/*.cs` |
+| `PayoutStatus` · `PayoutBatchStatus` · `EarningsState` | [payouts.md](payouts.md) | `Entities/Payouts/*.cs` |
+| `VerificationStatus` · `VerificationStepStatus` · `StepTypeCode` | [verification.md](verification.md) | `Entities/Verification/*.cs` |
+| `ModerationStatus` · `ModerationAction` | [reviews.md](reviews.md) | `Entities/Reviews/ReviewModerationStatus.cs` |
+| `TicketStatus` · `TicketCategory` · `TicketAuthorRole` | [tickets.md](tickets.md) | `Entities/Messaging/TicketCodes.cs` |
+| `CenterOnboardingState` | [partner-center.md](partner-center.md) | `Entities/PartnerCenters/` |
+| `BankAccountStatus` | [nurse.md](nurse.md) | bank-account entity |
+| roles · `Gender` | [auth.md](auth.md) | identity seed |
+| config/audit/holiday/alert codes | [admin.md](admin.md) | `Entities/Configuration/`, `Audit/`, `Holidays/`, `SupportAlerts/` |
+
+## What replaced what
+
+These files supersede [`archive/build-chain/contracts/domains/`](../../../archive/build-chain/contracts/domains/) — 17 hand-written files
+frozen 2026-07-13, plus the two `conventions/` files. Route-level content there held up well: an audit of
+every route those files name found **zero** that the live swagger lacks. What did not hold up:
+
+| Was | Now |
+| --- | --- |
+| `conventions/api-conventions.md`: body casing is "typically `snake_case` … derive from swagger" | **camelCase**, proven mechanically. [`../api-contract.md`](../api-contract.md#casing) |
+| `conventions/api-conventions.md`: server default `https://localhost:5002` | `http://localhost:5002` — plain HTTP (contradiction **C-3**) |
+| The envelope has 5 fields | It has **6** — `code` was added for machine-readable errors (REQ-003) |
+| Enum vocabularies spread across 17 files and the REQ ledger | One vocabulary block per domain file, cross-checked both ways |
+| `messaging.md` (851 B, headerless) silently amending `messaging-notifications-admin.md` | Merged: [tickets.md](tickets.md) + [notifications.md](notifications.md) + [admin.md](admin.md) (contradiction **C-8**) |
+| 17 files whose names matched *backend phases* | 22 files whose names match the **client's domains**, which is how the seam is actually consumed |
+| The REQ ledger as the change log you had to read to know the current shape | Each domain file states the current shape and lists only its **open** REQs |