feat(dx): mock API for local development (MSW) so the app runs without a backend

.github/workflows/ci.yml

@@ -24,3 +24,5 @@ jobs:
       - run: npm run test
 
       - run: npm run build
+
+      - run: npm run check:dist

ARCHITECTURE_ESSENTIALS.md

@@ -25,6 +25,13 @@ those first if you're new to the org, not just this file.
 ## Where things live
 - `src/services/` — API client calls to `docforum-core`. `api-client.ts` is
   the only place fetch/base-URL/error-envelope details live.
+- `src/mocks/` — MSW mock API for `npm run dev:mock` (issue #95). Handlers
+  mirror the same real/assumed contracts `src/services/` calls, over
+  obviously fake `example.test` fixtures. Loaded only behind the
+  `import.meta.env.DEV && VITE_ENABLE_MOCKS` guard in `main.tsx`, before
+  the first render; production bundles must never contain it — CI enforces
+  this via `npm run check:dist`. When an assumed contract in this file is
+  reconciled, update `src/mocks/` fixtures/handlers in the same PR.
 - `src/features/` — flow-specific logic (booking, referral-accept, order
   fulfillment selection, etc.) — one feature folder per PRD core flow.
 - `src/pages/` — route-level components.

CONTRIBUTING.md

@@ -20,6 +20,33 @@ to actually do anything: run `docforum-core`'s backend yourself (see its
 `CONTRIBUTING.md`), or point `VITE_API_BASE_URL` at a hosted instance.
 `npm run dev` defaults to `http://localhost:4000`.
 
+### Run with no backend at all: the mock API
+
+`npm run dev:mock` starts the same Vite dev server with an
+[MSW](https://mswjs.io)-backed mock of every endpoint the app calls —
+no `docforum-core` needed:
+
+- **Role switcher** — jump straight into the patient, doctor, facility or
+  admin experience (seeded personas with obviously fake data, all
+  `@example.test` emails). Logging in through the real login screen works
+  too; any email logs you in as the selected role.
+- **Scenarios** — toggle empty datasets and forced 500s to see empty and
+  error states without hand-crafting backend conditions.
+- **Latency** — delay every response (0–3 s) to check loading states.
+- **Reset data** — restore the fixture database after in-session
+  mutations (nothing is persisted; fixtures reset on reload).
+
+Mock handlers live in `src/mocks/` and sit on top of the fixtures in
+`src/mocks/fixtures.ts`. The app still reaches them through the normal
+service layer (`src/services/`), so screens behave exactly as they do
+against the real API. Mock code is excluded from production builds, and
+CI fails if it ever leaks (`npm run check:dist`).
+
+**When you add a service call to a new endpoint**, add a handler and
+fixtures in `src/mocks/` in the same PR, and cover it in
+`src/mocks/handlers.test.ts` — that's what keeps `dev:mock` honest as the
+API grows.
+
 ## 2. Find something to work on
 
 Open issues are scoped, real, and tagged with a complexity/point value

ROADMAP.md

@@ -86,6 +86,12 @@ real API" (no refresh-on-reload flow).
   a session exists, same caveat as the facility dashboard already had.
 - [ ] Link transaction hashes/escrows to the Stellar testnet explorer. Tracked as [issue #10](https://github.com/DocForum/docforum-web/issues/10) (Trivial, 100 pts).
 
+## Phase W7 — Platform quality: reliability, accessibility, performance, testing
+- [x] Mock API for local development (MSW). Tracked as [issue #95](https://github.com/DocForum/docforum-web/issues/95) (High, 200 pts) — `npm run dev:mock` serves every endpoint the app uses through the normal service layer via `src/mocks/`: seeded obviously-fake fixtures, a dev-panel role switcher (patient/doctor/facility/admin), scenario toggles (empty states, forced errors), a latency slider, and a fixture reset. 26 handler tests drive the real `src/services/` layer against MSW; CI fails if mock code ever enters a production bundle (`npm run check:dist`). Documented in `CONTRIBUTING.md`.
+- [ ] Generate MSW handlers and fixtures from the backend OpenAPI spec. Tracked as [issue #96](https://github.com/DocForum/docforum-web/issues/96) (High, 200 pts) — **blocked**: depends on [docforum-core#112](https://github.com/DocForum/docforum-core/issues/112) (OpenAPI 3.1 spec generated from the Zod schemas), which is still open — there is no authoritative `openapi.json` to generate from yet. Do not fabricate one; see that issue.
+- [ ] Storybook component library with interaction and accessibility tests. Tracked as [issue #97](https://github.com/DocForum/docforum-web/issues/97) (High, 200 pts).
+- [ ] Performance budget: route-level code splitting, lazy GSAP, and Lighthouse CI. Tracked as [issue #99](https://github.com/DocForum/docforum-web/issues/99) (High, 200 pts).
+
 ## Changelog
 - 2026-09-09 — Roadmap created, carved out of docforum-core Phase 7 as part
   of the 3-repo org split.