Refinement Phase 4 — Frontend de-mock (flip every domain to the real backend)

Mission: make the frontend actually call the backend. Today 21 of 22 client service domains default to an in-browser mock (USE_*_MOCK = true), so the running app is almost entirely fake data. Each domain's real clientApi already exists and maps the live routes 1:1 — the swap is a one-line flag flip per domain, once that domain's REQ gaps (Phase 3) are delivered and the demo data (Phase 1) exists. This phase flips them, in dependency order, and verifies each against the real API.

Track: frontend · Depends on: Phase 1, Phase 2, Phase 3 · Unlocks: a genuinely integrated app Before you start, read ../../phases/_shared/agent-operating-rules.md.

1. Context — where this sits

The frontend was deliberately built mock-primary so each phase could ship before its backend counterpart merged. Every domain follows the same seam: services/{domain}/apis/index.ts picks mockApi vs clientApi from a compile-time USE_{DOMAIN}_MOCK constant in constants.ts; the clientApi already wraps clientFetch and unwraps the ApiResult envelope. The design intent, recorded in every phase report and the mocks-registry, is: deliver the REQ → flip the flag → the domain is real, with no hook/component change.

This phase executes that flip for every domain. The order matters because the domains form a funnel — a domain whose inputs are still mocked can't meaningfully go real (e.g. bookingRequests needs search/patients/ addresses real first). Auth is already real and is the template.

Note on flags: the USE_*_MOCK constants are hard-coded literals, not env vars. Flipping means editing the constants.ts line to false. Consider (optional, small) refactoring each to read process.env.NEXT_PUBLIC_USE_{DOMAIN}_MOCK with a false default so environments can differ without code edits — but the minimum deliverable is the flags flipped to real.

2. Required reading (do this first)

dev/shared-working-context/reports/mocks-registry.md → the "Frontend client-side mocks" table. Every row lists the flag, the file, and the exact "Make it real →" precondition (which REQ + which upstream domain). This is your checklist.
client/CLAUDE.md → "services/" section (the per-domain descriptions + their REQ gaps).
client/src/services/auth/ → the already-real template for how a flipped domain behaves.
Each domain's apis/clientApi.ts (verify the routes it maps against the regenerated dev/contracts/openapi/swagger.v1.json — especially the ones Phase 3 flagged: partner-center kebab-case routes, BNPL provider_code, cancellation-policy codes).
The Phase 3 hand-off (which REQs actually landed) — only flip a domain whose gaps are delivered.

3. Scope — flip these, in this order

Flip each USE_*_MOCK to false only after its precondition holds, then run the domain's screens against the real backend and fix any real-path shape surprises. Group order mirrors the dependency funnel:

Group 1 — identity & reference (few/no gaps)

USE_GEOGRAPHY_MOCK — reference lookups; b4 live, no REQ needed. Flip early.
USE_PATIENTS_MOCK — needs REQ-005 (relation/conditions).
USE_PROFILES_MOCK — needs REQ-006 (avatar) + REQ-007 (name/language). uploadAvatar currently throws 501 until REQ-006.
USE_NURSE_BANK_MOCK — b3 live, no REQ. Flip.
USE_ADDRESSES_MOCK — needs REQ-008 (pin) + REQ-009 (provinceId).
USE_SERVICE_AREAS_MOCK — b4 live, no REQ. Flip.

Group 2 — catalog, verification, search (the discovery funnel)

USE_CATALOG_MOCK — b5 live; data caveat: a fresh backend has categories but no option groups until Phase 1 seeds them (or the f15 admin authors them). Flip only once option groups exist, or the variant builder's required-option step is empty.
USE_VERIFICATION_MOCK — needs REQ-011 (credential_details) + REQ-034 (admin queue/doc-URL/approve).
USE_SEARCH_MOCK — needs REQ-012 (name/avatar/distance + public profile). The linchpin of the funnel.

Group 3 — booking funnel

USE_BOOKING_REQUESTS_MOCK — needs REQ-013/014 and search/patients/addresses real (Groups 1–2).
USE_BOOKINGS_MOCK — a booking only exists after a paid request converts, so needs booking-requests + payment real. Also set NEXT_PUBLIC_EVV_MOCK_GPS=off to use real navigator.geolocation.
USE_PAYMENT_MOCK — needs REQ-016 (checkout summary) + REQ-017 (outcome/bookingId) + REQ-018 (invoice) and the upstream request flow real. Delete the dev mock-gateway harness page once flipped.

Group 4 — money reversal & post-booking

USE_REFUNDS_MOCK — needs REQ-019/020/021 (+ canonical cancellation codes) + REQ-035 (admin).
USE_BNPL_MOCK — needs REQ-022/023/024 (+ the balinyaar provider decision) + upstream real. Delete the BNPL gateway harness page once flipped.
USE_PAYOUTS_MOCK — needs REQ-025 (+ REQ-036 admin).
USE_REVIEWS_MOCK — needs REQ-026 (+ REQ-037 admin tagCodes).
USE_PATIENT_RECORDS_MOCK — the nurse visit-note half is already real (b14); the family-record half needs REQ-027 (and the product decision on whether it's a real entity). Flip only the parts that are backed; keep the family record mocked if the product defers it.

Group 5 — comms & admin consoles

USE_TICKETS_MOCK — needs REQ-028 + bookings real.
USE_NOTIFICATIONS_MOCK — b1 live; real once upstream domains actually dispatch notifications (the mock exists because nothing dispatches while upstreams are mocked). Flip after Groups 3–4.
USE_ADMIN_MOCK — needs REQ-029/030/031.
USE_PARTNER_MOCK — needs REQ-032/033 and the route-casing reconciliation (verify the kebab-case routes bind before flipping).

Cleanup

Remove the dev-only test harness pages once their domains are real: the payment mock-gateway (…/checkout/gateway/page.tsx) and the BNPL provider-handoff (…/checkout/bnpl/gateway/page.tsx) — on the real path the PSP/provider redirectUrl is an absolute URL, so these are never linked.
Remove the dev-only __mock* helpers (__mockApproveAll, __mockPublishSubmittedReview, __mockPushNotification, etc.) as their domains go real, or keep them behind a dev guard if still useful.

4. Mocks & seams in this phase

This phase retires mocks. The one client seam that legitimately stays is ILocationProvider (EVV GPS capture) — set NEXT_PUBLIC_EVV_MOCK_GPS=off to select the real navigator.geolocation. The AddressMapPicker remains a canvas stand-in until a real map widget is inlined (that's a separate design task, not a data mock).

5. Critical rules you must not get wrong

Don't flip a domain whose inputs are still mocked — you'll get empty screens or shape errors. Follow the group order; a domain is only real if the whole chain beneath it is.
Verify each clientApi's routes against the regenerated swagger before flipping — Phase 3 flagged three concrete casing/enum mismatches (partner-center kebab-case, BNPL balinyaar, cancellation codes). A wrong route silently 404s.
The flip is a flag, not a rewrite. If a screen needs a hook/component change to work on the real path, that's a Phase 3 gap that wasn't fully delivered — file/finish the REQ, don't hack the component.
npm run check and test:ci stay green after each flip; keep en.json/fa.json in sync (no new strings expected, but empty/error states may surface copy that was never exercised on the mock path).
Real error/empty states now matter. The mocks always returned tidy data; real endpoints 404/return empty. Verify each domain's empty, error, and loading states against the real backend — this is where mock-only apps break.

6. Definition of Done

On top of the shared definition-of-done.md:

Every domain whose REQ preconditions are met has USE_*_MOCK = false and is verified working against the real backend; any domain still mocked is because its REQ/product decision is explicitly outstanding (documented, not forgotten).
npm run check + npm run test:ci green; translations in sync.
The full happy path runs on real data end-to-end: log in → browse categories → search → open a nurse profile → request a booking → nurse accepts → checkout → confirmation → booking detail → review.
Dev test-harness pages + __mock* helpers for real domains removed or dev-guarded.
client/CLAUDE.md and the mocks-registry updated to reflect which domains are now real.

7. How to test (what a human can verify after this phase)

With client + server running on real data (Phases 0–3 done), open the app and confirm the Network tab shows real /api/v1/* calls for every screen (not just auth) — no domain is serving in-browser mock data.
Walk the customer funnel: home category grid → search (real seeded nurses) → nurse profile → request → (switch to the nurse account) accept → (customer) checkout → pay (mock gateway is gone; on a real PSP this is Phase 8, but the request→booking conversion works) → confirmation → booking detail.
Nurse funnel: verification flow, services builder, coverage, requests inbox, visits/EVV, earnings — all on real data.
Admin: verification queue, refunds, payouts, moderation, config/holidays/audit, partner centers — on real data with role-gated nav (Phase 2).
Confirm empty/error states render correctly where the demo data is sparse (e.g. a nurse with no reviews).

8. Hand off & document (close the phase)

Update client/CLAUDE.md "services/" notes and dev/shared-working-context/reports/mocks-registry.md (frontend mocks table) to mark each flipped domain real.
Report the flip status of all 22 domains (real / still-mocked-because-X) and any real-path surprises found. Save a memory note on the de-mock order and any domain that needed a Phase-3 follow-up.

10 KiB Raw Blame History Unescape Escape