Mocking vs. Real Backend
During Intake, Claude asks whether your backend API is running. Your answer decides where the app gets its data, together with whether you supplied an OpenAPI spec.
How Claude decides
Section titled “How Claude decides”| Your backend | What Claude does |
|---|---|
| Running, with a spec | Connects to it directly and runs a connection test during Intake |
| Running, no spec | Connects to it directly and writes an API spec as it builds, marking the endpoints it inferred |
| Still in development | Builds a mock so the app works now. You switch to the real backend later with /api-go-live. |
| No backend | Builds a mock that the app keeps using |
If Claude inferred any endpoints for a backend that’s still being built, the manual test asks you to confirm they match the real API.
How the mock works
Section titled “How the mock works”The mock uses MSW (Mock Service Worker), which intercepts the app’s API calls in the browser and answers them with realistic data. No backend server needs to run.
| Location | What it holds |
|---|---|
web/src/mocks/handlers.ts | The mock response for each endpoint |
web/src/mocks/data/ | The sample records the mock and the tests share |
web/public/mockServiceWorker.js | The service worker MSW runs in the browser |
The mock and the automated tests use the same sample records, so the two can’t drift apart. Claude creates the mock with the first epic that needs one, and later epics add their endpoints to it.
The setting NEXT_PUBLIC_USE_MOCK_API=true in web/.env.local turns the mock on. Every API call goes through the app’s API client, so switching between the mock and the real backend needs no code changes.
What the mock covers
Section titled “What the mock covers”If you supplied an OpenAPI spec, the mock covers the endpoints your app uses, with responses that match the spec’s shapes. Without a spec, Claude infers the API shape from your requirements and mocks against that. Sample data from documentation/ fills the mock responses where possible.
Switching to your real backend
Section titled “Switching to your real backend”When your backend is ready, type /api-go-live. It:
- Asks for your live API’s address, and whether to keep the mock files for reference.
- Re-runs the connection test from Intake against that address.
- Sets
NEXT_PUBLIC_API_BASE_URLinweb/.env.localand removes theNEXT_PUBLIC_USE_MOCK_APIline. - Scans your code for leftover mock data that could hide a real problem.
- Removes the mock files, if you chose to.
- Gives you a go-live checklist of things to test against the real backend.
If the connection test fails, /api-go-live stops without changing anything and tells you the likely cause, such as a wrong URL or an expired token. You can choose to switch anyway, and Claude records that the test failed.
Restart the dev server after the switch so the app picks up the new settings.
NEXT_PUBLIC_USE_MOCK_API is fixed into the app when it’s built. Make sure it isn’t set when you build for production, or the deployed app will serve mock data.
Keeping the mock up to date
Section titled “Keeping the mock up to date”If your API spec changes, update it in documentation/ and type /api-mock-refresh. Claude regenerates only the handlers for endpoints that changed, and keeps the data you’ve already adjusted for the rest.
To see where each endpoint stands, type /api-status. It shows which endpoints are mocked and where each came from, and flags any drift between the spec and the mocks. It also reports whether the backend connection is working.