# Mock Endpoints Guide (Generic)

This document explains how the dev mock API layer works in general.

## Scope

- Mocks are active only in Vite dev server mode.
- Mocks are never used in production build/runtime.
- Mocks intercept `POST /api?route=<Controller:method>` calls.

## Enable Mock Mode

1. Go to `redcap_v999.0.0/Resources/js/vue/components`
2. Run `npm run dev:mock`
3. Confirm requests go to Vite `/api` (not directly to REDCap backend URL)

If requests bypass Vite and hit backend directly, mocks will not run.

## Config File Resolution

Startup uses the first available:

1. `VITE_API_MOCK_FILE`
2. `VITE_BTG_VERIFY_PROTECTION_MOCK_FILE` (legacy compatibility)
3. Default `dev-mocks/btg-verify-protection.json`

## Current JSON Structure

```json
{
  "defaults": {
    "<featureName>": {},
    "state": {}
  },
  "projects": {
    "<pid>": {
      "<featureName>": {},
      "state": {}
    }
  }
}
```

## Project Overrides

- Query param `pid` selects project overrides.
- If `projects.<pid>` exists, it is merged over `defaults`.
- This allows project-specific behavior without changing code.

## Add Future Mock Endpoints

1. Create a feature subfolder in `dev-mocks/endpoints/<feature>/` (example: `btg`)
2. Add endpoint modules in that feature folder
3. Keep shared feature utilities (parsers/state/helpers) in the same feature folder
4. Register endpoints in `dev-mocks/endpoints/index.js`
5. Add docs file in `dev-mocks/docs/` for that feature
6. Keep cross-feature helpers separate from feature folders only when truly generic

## Troubleshooting

`I changed JSON but behavior did not change`
- Ensure Vite mock mode is running: `npm run dev:mock`
- Ensure app is loaded from Vite dev server and requests go to `/api`
- Ensure JSON is valid

`I only see backend data`
- Expected for endpoints that are not mocked.
- Example: BTG patient list endpoint is intentionally backend-driven.
