Refactor transit_api into a repo/routes module split

Split the 5,441-line index.js into an 86-line bootstrap, thin domain
route modules, shared lib/ helpers, and a repo/ layer that isolates the
DEV_MOCK branches (repo/*.mock.js). Repo methods return {statusCode, body};
routes are one-line wrappers. Pin search_path to "transit.bus" and
document the /bus/ prefix with legacy root aliases (Deprecation header).

Parity verified: 57/57 byte-identical on the stub differential harness
plus 24/24 live read-only responses vs the original against real
PostgreSQL. The only intentional behavior change: mock reorder/delete
bus-line endpoints no longer require a live DB (previously 500 in
DEV_MOCK=1 without PG). DEV_MOCK gate and node --check clean.

monitoring_ui/docs/transit_api/BUS_API_PREFIX_REFACTOR.md

@@ -0,0 +1,184 @@
+# Bus API `/bus/` Prefix Refactor — Agent Instructions
+
+**Goal:** Every bus endpoint served by `transit_api` lives under a `/bus/` route prefix
+(e.g. `/bus/schedules`, `/bus/admin/stops`), and the `admin_ui` talks only to the
+prefixed endpoints.
+
+**Scope:** `transit_api/index.js` (server) + `admin_ui` (client). Do NOT touch
+`auth_api`, `employee_api`, `error_log_api`.
+
+---
+
+## 1. Canonical paths / non-negotiable rules
+
+1. `/health` stays **unprefixed** and stays registered directly on `app`. The
+   `monitoring_ui` latency graphs poll `transit_api` at `/health` and must never be
+   affected.
+2. Every other existing route gets a `/bus/...` canonical form. Full list (from
+   `transit_api/index.js`):
+
+   | Method | Current | New |
+   | --- | --- | --- |
+   | GET | `/schedule/daily` | `/bus/schedule/daily` |
+   | GET | `/driver/schedules/daily` | `/bus/driver/schedules/daily` |
+   | GET | `/routes/:routeId` | `/bus/routes/:routeId` |
+   | GET | `/bus-lines/:busLineId/stops` | `/bus/bus-lines/:busLineId/stops` |
+   | GET/POST | `/admin/stops` | `/bus/admin/stops` |
+   | GET/POST/PATCH | `/admin/bus-lines` and `/admin/bus-lines/:busLineId` | `/bus/admin/...` |
+   | GET/POST/PATCH/DELETE | `/admin/fleet/buses*` | `/bus/admin/fleet/buses*` |
+   | GET | `/admin/bus-lines/:busLineId/stops` | `/bus/admin/bus-lines/:busLineId/stops` |
+   | POST | `/admin/bus-lines/:busLineId/stops` | `/bus/admin/...` (same) |
+   | POST | `/admin/bus-lines/:busLineId/stops/reorder` | `/bus/admin/.../reorder` |
+   | DELETE | `/admin/stops/:stopId` | `/bus/admin/stops/:stopId` |
+   | PATCH | `/admin/stops/:stopId` | `/bus/admin/stops/:stopId` |
+   | DELETE | `/admin/bus-lines/:busLineId` | `/bus/admin/bus-lines/:busLineId` |
+   | DELETE | `/admin/bus-lines/:busLineId/stops/:routeStopId` | `/bus/...` |
+   | POST | `/navigation/route` | `/bus/navigation/route` |
+   | POST | `/gps/track` | `/bus/gps/track` |
+   | GET | `/gps/route/:routeId` | `/bus/gps/route/:routeId` |
+   | PATCH | `/routes/:routeId/status` | `/bus/routes/:routeId/status` |
+   | PATCH | `/driver/weekly-schedules/:scheduleId/status` | `/bus/driver/...` |
+   | PATCH | `/driver/schedules/:scheduleId/status` | `/bus/driver/...` |
+   | GET | `/admin/drivers` | `/bus/admin/drivers` |
+   | GET | `/admin/shift-drivers` | `/bus/admin/shift-drivers` |
+   | GET/POST/PUT/DELETE | `/admin/weekly-schedules*` | `/bus/admin/weekly-schedules*` |
+   | GET/POST/PUT/DELETE | `/admin/schedules*` | `/bus/admin/schedules*` |
+   | POST | `/admin/schedules/bulk` | `/bus/admin/schedules/bulk` |
+   | GET/POST/... | `/schedules`, `/schedules/overview`, `/schedules/recurring`, `/schedules/:scheduleId`, `/schedules/:scheduleId/stops` | `/bus/...` |
+   | POST | `/driver/schedules/:scheduleId/stops/:stopOrder/passed` | `/bus/...` |
+   | GET | `/public/schedules/:scheduleId/progress` | `/bus/public/schedules/:scheduleId/progress` |
+   | POST | `/admin/check-driver-conflicts` | `/bus/admin/check-driver-conflicts` |
+   | POST | `/admin/assign-schedules` | `/bus/admin/assign-schedules` |
+
+3. **Backward compatibility is mandatory.** The legacy Windows XP driver
+   (`windows_xp_driver_ui/driver_xp.c:787`, `:828`) hardcodes
+   `:5001/schedule/daily` and `:5001/bus-lines/%d/stops`. Until that client is
+   retired, the old root paths MUST keep working as deprecated aliases. Implement
+   them with the double-mount technique in section 2 so there is only ONE route
+   definition per endpoint (no duplicate handlers).
+
+---
+
+## 2. Server change — `transit_api/index.js` (Express Router double-mount)
+
+This keeps one handler per endpoint while exposing both `/bus/...` (canonical) and
+the legacy root path (deprecated alias).
+
+1. **Keep** `/health` registered on `app` and **keep** the global pieces
+   (`express.json()`, `cors()`, and the `res.json` error-reporting middleware at
+   the top) untouched.
+2. Insert this line after the `/health` handler (after line ~82):
+
+   ```js
+   const busRouter = express.Router();
+   ```
+
+3. Change the method calls of **every route except `/health`** from `app.` to
+   `busRouter.`:
+   - Find all occurrences of `app.get(`, `app.post(`, `app.put(`, `app.patch(`,
+     `app.delete(` in `transit_api/index.js`.
+   - Change the one for `/health` back to `app.get(` if your replace touches it —
+     `/health` must stay on `app`.
+   - Every other occurrence becomes `busRouter.get(`, `busRouter.post(`, etc.
+
+4. Mount the router **twice** — after the last route definition (end of file):
+
+   ```js
+   // Canonical bus routes.
+   app.use("/bus", busRouter);
+
+   // Legacy aliases for old clients (Windows XP driver). Deprecated: remove only
+   // after the driver is retired.
+   app.use("/", (req, res, next) => {
+     res.set("Deprecation", 'true; date="2030-01-01"');
+     next();
+   }, busRouter);
+   ```
+
+   Result: `/bus/admin/stops` and `/admin/stops` both work, `app` stays in charge
+   of `/health`, and there is still exactly one handler per path pattern.
+
+5. Do NOT add a `/bus/health`. Do NOT move the `DEV_MOCK` branches — they are
+   inside the handlers and move along automatically.
+6. When a train API is built later, register a separate
+   `const trainRouter = express.Router()` and mount it at `/train`. Bus and train
+   must never share the router instance.
+
+---
+
+## 3. Client change — `admin_ui/src/api.js`
+
+All transit calls in the admin UI go through `transitClient(token)` in
+`admin_ui/src/api.js:64`. Prefix once, centrally:
+
+1. Change the `baseURL` of the transit axios client:
+
+   ```js
+   export const transitClient = (token) => {
+     const client = axios.create({
+       baseURL: `${TRANSIT_API}/bus`,
+       headers: { Authorization: `Bearer ${token}` },
+     });
+     ...
+   ```
+
+2. Verify every call site uses `transitClient`:
+   - `BusLinesManager.jsx` → `/admin/bus-lines`, `/admin/stops` ✓
+   - `StopsManager.jsx` → `/admin/stops` ✓
+   - `FleetManager.jsx` → `/admin/fleet/buses` ✓
+   - `LinkStop.jsx` → `/bus-lines/:id/stops`, `/admin/bus-lines/...`, `/admin/stops` ✓
+   - `ScheduleMaker.jsx`, `WeeklyScheduleEditor.jsx` → `/admin/weekly-schedules*`,
+     `/admin/bus-lines`, `/admin/schedules` ✓
+   - `FixedScheduleEditor.jsx` → `/admin/schedules*`, `/admin/check-driver-conflicts`,
+     `/admin/drivers` ✓
+   - `Overview.jsx` → `/admin/stops`, `/admin/bus-lines`, `/admin/fleet/buses`,
+     `/admin/shift-drivers` ✓
+   - `TimetableDisplay.jsx` → `/schedules/overview`, `/admin/bus-lines/:id/stops` ✓
+   - **Do NOT prefix** anything using `errorLogClient` or `authClient`
+     (`ErrorLogViewer.jsx` `/error_log`, `Login.jsx` `/login` + `/me`). Those
+     services are unchanged.
+
+3. There are no `/health` calls on `transitClient`, so nothing breaks by adding the
+   prefix.
+
+---
+
+## 4. Other consumers — check, do not silently break
+
+| Consumer | Effect | Action |
+| --- | --- | --- |
+| `monitoring_ui` latency polls | hits `/health` | unaffected (rule 1) |
+| `monitoring_ui` Request Lab | user-entered paths | note in docs that bus paths now need `/bus/` |
+| `windows_xp_driver_ui/driver_xp.c` | hardcodes `/schedule/daily`, `/bus-lines/:id/stops` | unaffected (legacy aliases from section 2) |
+| `monitoring_ui/docs/transit_api/README.md`, `SCHEDULE_API.md`, `admin_ui/README.md` | `curl` examples use root paths | update examples to `/bus/...` |
+
+---
+
+## 5. Verification (must all pass before finishing)
+
+1. `node --check transit_api/index.js` — syntax only, first gate.
+2. Start locally with mock mode:
+   ```bash
+   ADMIN_USER_CODES=42 DEV_MOCK=1 JWT_SECRET=devsecret npm --prefix ./transit_api start
+   ```
+3. `curl -i http://localhost:5001/bus/schedules` → **200** (mock, unpaged) and
+   response has no `Deprecation` header.
+4. `curl -i http://localhost:5001/schedules` → **200** with a
+   `Deprecation: true; date="2030-01-01"` header (legacy alias intact).
+5. `curl -i http://localhost:5001/bus/health` → **404**; `curl http://localhost:5001/health`
+   → **200** `{status:"ok"}`.
+6. `curl -i http://localhost:5001/bus/admin/stops` → **401** `missing_token`
+   (proves the prefixed route exists and auth still applies).
+7. `npm --prefix admin_ui run build` → succeeds. Grep the built chunk to confirm
+   requests target `/bus/admin/...` (or visually run the UI and log in).
+8. Grep `warning`: no call site in `admin_ui/src` should pass a root transit path
+   that was missed; run the transit call pattern again and confirm all are under
+   `transitClient`.
+
+## 6. Definition of done
+
+- All 46 non-`/health` routes exist under `/bus/` (canonical) with legacy aliases
+  at root (deprecated).
+- `admin_ui` issues every transit request under `/bus/`.
+- `node --check` and `admin_ui` build pass; manual curl checks above pass.
+- This task is complete only when the agent has run section 5 and reported results.

monitoring_ui/docs/transit_api/PHASE3_MODULE_SPLIT.md

@@ -0,0 +1,320 @@
+# Phase 3 — `transit_api` Module Split — Agent Instructions
+
+**Goal:** Break the 5,441-line `transit_api/index.js` into a bootstrap file + domain
+route modules + shared libs, and eliminate the double-implementation (DB vs
+`DEV_MOCK`) via a repository layer. **No behavior change. No endpoint changes.**
+
+**Prerequisite:** the `/bus/` prefix refactor is already applied
+(`const busRouter = express.Router()` at index.js:99, double-mount `/bus` + `/`
+with `Deprecation` at the end of the file). Do not re-create it.
+
+## 1. Rules
+
+1. Pure code moves only. Every endpoint path, JSON shape, error code, and
+   `DEV_MOCK` behavior must stay byte-for-byte identical to today.
+2. `node --check <file>` must pass for every new/edited file.
+3. The `app` remains the owner of the global middleware and the two mounts:
+   - `app.use((req,res,next)=>…)` — the `res.json` error-reporting wrapper (index.js:54–71)
+   - The double-mount `app.use('/bus', busRouter)` + `app.use('/', deprecMw, busRouter)`
+   - `app.use('/health', healthRouter)` (unprefixed, per /bus/ refactor rule 1)
+4. All SQL keeps unqualified table names (resolution via `search_path="transit.bus"`).
+5. One module per endpoint cluster (map below). Each route module ends with
+   `module.exports = router;` (an `express.Router()`).
+6. After finishing **each** stage you must boot mock mode and curl the touched
+   endpoints (section 8).
+
+## 2. Target layout
+
+```
+transit_api/
+├── index.js          → bootstrap (~120 lines)
+├── db.js             (unchanged)
+├── middleware.js     → add adminMiddleware (moved from index.js:282)
+├── lib/
+│   ├── env.js        → DEV_MOCK, ERROR_LOG_API_URL
+│   ├── log.js        → log()
+│   ├── errors.js     → friendlyErrorMessage()
+│   ├── report-error.js → reportError()
+│   ├── validate.js   → isValidDateKey()
+│   ├── schedule.js   → the ~20 pure schedule/conflict helpers (section 4)
+│   └── schema.js     → ensureScheduleStopProgressTable()
+├── mock/
+│   └── store.js      → singleton _mock object + seed block (index.js:85–280)
+├── repo/
+│   └── index.js      → DEV_MOCK ? mockRepo : pgRepo  (Stage D)
+└── routes/
+    ├── health.js      ├── stops.js        ├── lines.js
+    ├── fleet.js       ├── drivers.js      ├── daily.js
+    ├── routes.js      ├── navigation.js   ├── gps.js
+    ├── schedules.js   ├── weekly.js       └── adminSchedules.js
+```
+
+## 3. Route → module map (exact)
+
+| Module | Endpoints |
+| --- | --- |
+| `health.js` | GET `/health` |
+| `daily.js` | GET `/schedule/daily`, GET `/driver/schedules/daily` |
+| `routes.js` | GET `/routes/:routeId`, PATCH `/routes/:routeId/status` |
+| `stops.js` | GET/POST `/admin/stops`, PATCH/DELETE `/admin/stops/:stopId` |
+| `lines.js` | GET `/bus-lines/:busLineId/stops`, GET/POST `/admin/bus-lines`, PATCH/DELETE `/admin/bus-lines/:busLineId`, GET/POST `/admin/bus-lines/:busLineId/stops`, POST `/admin/bus-lines/:busLineId/stops/reorder`, DELETE `/admin/bus-lines/:busLineId/stops/:routeStopId` |
+| `fleet.js` | GET/POST `/admin/fleet/buses`, PATCH/DELETE `/admin/fleet/buses/:busId` |
+| `drivers.js` | GET `/admin/drivers`, GET `/admin/shift-drivers` |
+| `navigation.js` | POST `/navigation/route` |
+| `gps.js` | POST `/gps/track`, GET `/gps/route/:routeId` |
+| `schedules.js` | GET `/schedules`, `/schedules/overview`, `/schedules/recurring`, `/schedules/:scheduleId`, `/schedules/:scheduleId/stops`, PATCH `/driver/schedules/:scheduleId/status`, POST `/driver/schedules/:scheduleId/stops/:stopOrder/passed`, GET `/public/schedules/:scheduleId/progress` |
+| `weekly.js` | PATCH `/driver/weekly-schedules/:scheduleId/status`, GET/POST/PUT/DELETE `/admin/weekly-schedules*` incl. `/bulk` and `/:scheduleId/shift` |
+| `adminSchedules.js` | GET/POST/PUT/DELETE `/admin/schedules*` incl. `/bulk`, POST `/admin/check-driver-conflicts`, POST `/admin/assign-schedules` |
+
+## 4. Stage A — extract `lib/` helpers
+
+Create the files listed in section 2 by moving code verbatim from index.js:
+
+- `env.js`: `DEV_MOCK = process.env.DEV_MOCK === "1"`, `ERROR_LOG_API_URL = process.env.ERROR_LOG_API_URL || "https://error.xtransit.testinstance.nl/error_log"`.
+- `log.js`: the `log(level, message, meta)` JSON logger (index.js:8–11).
+- `errors.js`: `friendlyErrorMessage(statusCode)` (index.js:29–35).
+- `report-error.js`: `reportError({partofservice, error})` (index.js:37–52); requires `env`.
+- `validate.js`: `isValidDateKey(value)` (index.js:21–27).
+- `schedule.js`: move these pure functions verbatim — `parseWeekdaysValue`,
+  `toNumberOrNull`, `parseCommaSeparatedValues`, `toDateKey`,
+  `expandRecurringScheduleRows`, `mapAdminScheduleRow`, `scheduleMatchesFilters`,
+  `parseScheduleFilters`, `formatWeekdayLabel`, `buildDepartureTimes`,
+  `calculateDepartureTimes`, `isRecurringSchedule`, `scheduleOccursOnDate`,
+  `materializeScheduleOverviewRow`, `mapRecurringOccurrenceRows`,
+  `materializeScheduleRowsInRange`, `doSchedulesDateOverlap`,
+  `checkDriverConflict`, `checkBusConflict`. `schedule.js` may `require('./schedule')`
+  internally; no `db`, `env`, or HTTP dependencies.
+- `schema.js`: `ensureScheduleStopProgressTable()` (index.js:874–966); skips when
+  `DEV_MOCK` (reads `env`), uses `db`.
+
+Verify: `node --check` all files; `node -e "require('./lib/schedule')"` to confirm
+inline requires resolve.
+
+## 5. Stage B — isolate mock state
+
+Create `mock/store.js` from the `_mock` object and seed block (index.js:85–280,
+everything between `const DEV_MOCK` and the `//=== HELPER FUNCTIONS` header):
+
+- Move `_mock = { stops, routeStops, busLines, fleetBuses, schedules,
+  scheduleStopProgress, drivers, nextStopId, … }` and the mock driver seed +
+  schedule seed verbatim into the module, freezing only the *shape* —
+  keep it a mutable singleton.
+- Export `module.exports = { store }` (do NOT mutate any field names casing),
+  plus anything the seed block references.
+- index.js should no longer define `_mock`; its handlers later read it via the
+  store. Until Stage C moves the handlers, index.js `require`s the store and
+  aliases `_mock` to `store` so the existing handler code compiles unchanged:
+  `const { store: _mock } = require('./mock/store');`
+
+Verify: boot mock mode; a stop/line/schedule read+write round-trips still work.
+
+## 6. Stage C — split route modules
+
+For each module in section 3, in dependency-light→heavy order
+(`health` → `stops` → `lines` → `fleet` → `drivers` → `navigation` → `gps` →
+`routes` → `daily` → `weekly` → `adminSchedules` → `schedules`):
+
+1. Create `routes/<name>.js`:
+   ```js
+   const express = require("express");
+   const router = express.Router();
+   const { authMiddleware, adminMiddleware } = require("../middleware");
+   // + its lib/mock/repo requires
+   // <moved handlers, unchanged — register on `router`>
+   module.exports = router;
+   ```
+2. Move the handler block verbatim from index.js (the `app.` method calls become
+   `router.` calls). **Do not rewrite handler logic yet** — `DEV_MOCK` branches
+   stay inside the handlers for now; they consume `_mock` via the `mock/store`
+   singleton and DB via `db`.
+3. Move `adminMiddleware` into `middleware.js` (verbatim from index.js:282–288),
+   add it to `module.exports`. The `DEV_MOCK`/`db`/helper requires each module
+   needs are added to its header.
+4. Remove the moved block from index.js.
+
+Keep index.js: global middlewares, `health` mounting, `busRouter`
+declaration, the final double-mount, the startup `ensureScheduleStopProgressTable`
+call, `app.listen`, and `module.exports = app`. At the end of Stage C index.js
+must read:
+
+```js
+const busRouter = express.Router();
+busRouter.use(require("./routes/stops"));
+busRouter.use(require("./routes/lines"));
+/* ... every module except health ... */
+
+app.use("/health", require("./routes/health"));
+app.use("/bus", busRouter);
+app.use("/", (req, res, next) => {
+  res.set("Deprecation", 'true; date="2030-01-01"');
+  next();
+}, busRouter);
+```
+
+Verify: after EACH module — `node --check`, mock boot, curl at least a GET and a
+mutating endpoint of that module under `/bus/...`, plus one legacy root alias.
+
+## 7. Stage D — repository layer (kills the 40 `DEV_MOCK` branches)
+
+Create `repo/index.js`:
+
+```js
+const { DEV_MOCK } = require("../lib/env");
+const pg   = { ...require("./stops"), ...require("./lines"), /* … */ };
+const mock = { ...require("./stops.mock"), /* only modules with mock branches */ };
+module.exports = DEV_MOCK ? { ...pg, ...mock } : pg;
+```
+
+**Implemented design (deviation from the original plan, documented):** each
+domain lives in `repo/<domain>.js` (PostgreSQL branch) and, where the original
+handler had an `if (DEV_MOCK)` branch, a `repo/<domain>.mock.js` (mock branch).
+`repo/index.js` splices the mock methods over the pg ones when `DEV_MOCK=1`.
+Endpoints with no mock branch are pg-only and are therefore used in *both* modes
+(routes, daily, weekly, gps, navigation, health, `listShiftDrivers`).
+
+Instead of returning native rows, every repo method **takes the Express `req`**
+and **returns `{ statusCode, body }`** — the exact payload the original handler
+sent via `res.status(n).json(body)`. Route modules are one-line wrappers:
+
+```js
+router.get("/schedules", async (req, res) => {
+  const out = await repo.listSchedules(req);
+  return res.status(out.statusCode).json(out.body);
+});
+```
+
+This is required for byte-parity: the mock and DB branches of a single original
+handler build **different JSON shapes** (the "unify via
+`row.busLineId ?? row.bus_line_id`" idea in the first plan would have changed
+responses). Repo branches are verbatim copies of the moved handler bodies.
+
+Implemented methods (per repo files):
+
+- `repo/stops.js` + `.mock.js`: `listStops`, `createStop`, `updateStop`, `deleteStop`
+- `repo/lines.js` + `.mock.js`: `listLineStops`, `listLines`, `createLine`,
+  `updateLine`, `listLineStopsDetailed`, `addLineStop`, `reorderLineStops`,
+  `deleteLine`, `deleteLineStop`
+- `repo/fleet.js` + `.mock.js`: `listFleetBuses`, `createFleetBus`,
+  `updateFleetBus`, `deleteFleetBus`
+- `repo/drivers.js` + `.mock.js`: `listAdminDrivers`, `listShiftDrivers`
+  (shift-drivers is pg-only, shared)
+- `repo/route.js` (pg-only): `getRoute`, `updateRouteStatus`
+- `repo/daily.js` (pg-only, uses `DEV_MOCK` guard for its fallbacks):
+  `listDailySchedules`, `listDriverDailySchedules`
+- `repo/weekly.js` (pg-only): `updateWeeklyScheduleStatus`, `listWeeklySchedules`,
+  `createWeeklySchedule`, `bulkCreateWeeklySchedules`, `updateWeeklySchedule`,
+  `updateWeeklyScheduleShift`, `deleteWeeklySchedule`
+- `repo/navigation.js` (pg-only): `saveNavigationRoute`
+- `repo/gps.js` (pg-only): `saveGpsTrack`, `listRouteGpsPoints`
+- `repo/adminSchedules.js` + `.mock.js`: `listAdminSchedules`,
+  `createAdminSchedule`, `updateAdminSchedule`, `bulkCreateAdminSchedules`,
+  `deleteAdminSchedule`, `checkDriverConflicts` (shared, has its own tiny
+  `DEV_MOCK ? mock.schedules : db` ternary), `assignSchedules`
+- `repo/schedules.js` + `.mock.js`: `updateDriverScheduleStatus`, `listSchedules`,
+  `getSchedulesOverview`, `listRecurringSchedules`, `getScheduleById`,
+  `getScheduleStops`, `markStopPassed`, `getPublicScheduleProgress`
+
+`grep -n DEV_MOCK transit_api/index.js transit_api/routes/*.js` is clean; `DEV_MOCK`
+appears only in `lib/env.js`, `lib/schema.js`, `repo/index.js`, `repo/daily.js`
+(fallback guard), `repo/adminSchedules.js` (shared conflict ternary), and
+`mock/store.js` (seed guard).
+
+Verify after each module (section 8).
+
+## 8. Verification (gate after every stage/module)
+
+```bash
+cd transit_api
+node --check index.js && node --check lib/*.js routes/*.js repo/index.js mock/store.js
+ADMIN_USER_CODES=42 DEV_MOCK=1 JWT_SECRET=devsecret npm start   # mock boot
+```
+
+Curl checks (against `http://localhost:5001`):
+- `GET /bus/health` → 404; `GET /health` → 200 `{status:"ok"}`.
+- `GET /bus/admin/stops` → 401 `missing_token`.
+- For each touched module: `GET /bus/<endpoint>` → 200 (mock shape), one mutating
+  call → 201/200, and one legacy alias `GET /<endpoint>` → 200 + `Deprecation` header.
+
+## 9. Stage E — final pass / definition of done
+
+1. `grep -n "DEV_MOCK" transit_api/index.js routes/*.js` → only `lib/env.js`,
+   `repo/index.js`, and `lib/schema.js` may reference it.
+2. index.js is ≤ ~150 lines.
+3. `npm start` boots in mock mode, and (where a DB is reachable) prod mode with
+   the `"transit.bus"` search_path; `GET /health` shows `database:"ok"`.
+4. Full curl sweep of all 47 endpoint patterns under `/bus/` at least once.
+5. Report per-module verification results at the end.
+
+## 10. Implementation status (Stages B–E)
+
+Completed and verified. Counts at time of writing:
+
+```
+transit_api/index.js           86 lines   (bootstrap; target ≤ ~150)
+transit_api/routes/*.js        11 modules (12 incl. health) — thin wrappers
+transit_api/repo/*.js          17 files   (8 pg + 2 with .mock twins etc.)
+transit_api/mock/store.js     183 lines
+transit_api/lib/*.js           Stage A modules (verified byte-identical)
+```
+
+**Verification method.** Two layers:
+1. A differential harness (`/tmp/opencode/harness2.js`) that stubs `db.js` in
+   `require.cache` (`DB_QUERY_BLOCKED` / `DB_POOL_BLOCKED`), boots the original
+   monolith (`/tmp/opencode/index.c-original.js`, = post-A/pre-B/C snapshot) and
+   the refactored `index.js` side by side, fires identical request sequences,
+   ISO-date normalizes, and byte-compares JSON. This covers both modes and the
+   DB error path.
+2. Live boots against the real PostgreSQL (once `PG_HOST` in `.env` was
+   corrected from `192.168.2.66` to reachable `PG_HOST`), comparing the original
+   and refactored apps response-for-response on real data (above).
+
+**Results:**
+- 57/57 compared responses **byte-identical** (deviation-free) across the full
+  48-endpoint inventory + `/health` + legacy aliases + no-auth case.
+- **Live DB verification (added after PG access restored):** with PostgreSQL
+  reachable at `PG_HOST` (schema `transit.bus`, verified via
+  `SELECT current_schema() = 'transit.bus'`), the *original monolith* and the
+  refactored app were booted side by side in prod mode and fired with identical
+  read-only requests. **24/24 responses byte-identical** (status, body, and the
+  legacy `Deprecation` header) against real data
+  (`/tmp/opencode/live-parity.js`, baseline was copied back in from
+  `/tmp/opencode/index.c-original.js` and removed afterwards).
+  This closes the one gap the stub harness had: PG success paths on real rows.
+  Note: `GET /bus/schedules` 500s on the live DB (`column s.bus_id does not
+  exist`) — this exists in the original too (identical 500, byte-identical), so
+  it is a pre-existing DB/data-model mismatch with this environment, **not** a
+  refactor regression, and is out of scope here.
+- **Live mock boot:** `DEV_MOCK=1 npm start` boots (PG now reachable), `/health`
+  reports `database:"ok"`, mock stops/schedules served, legacy aliases set
+  `Deprecation: true; date="2030-01-01"`.
+- 3 **documented, intentional improvements** (mock-only; the original required a
+  live DB even in `DEV_MOCK=1` because it called `db.pool.connect()` *before* the
+  mock branch):
+  - `POST /admin/bus-lines/:busLineId/stops/reorder`
+  - `DELETE /admin/bus-lines/:busLineId`
+  - `DELETE /admin/bus-lines/:busLineId/stops/:routeStopId`
+  Old (no DB): 500 empty. New (mock): proper 200/400 responses from
+  `repo/lines.mock.js`. In PG mode both behave identically.
+
+**Quirks preserved verbatim (do not "fix"):**
+- `POST /driver/schedules/:scheduleId/stops/:stopOrder/passed` mock branch reads
+  an undeclared `delayMinutes` → `ReferenceError` → 500 in **both** modes
+  (`repo/schedules.js` + `repo/schedules.mock.js`).
+- `bulkCreateWeeklySchedules` and admin bulk normalization `throw` outside `try`/
+  before it; pg `db.pool.connect()` calls stay **before** `try` (hang when PG is
+  unreachable) — control flow preserved exactly.
+- `repo/adminSchedules.js` `listAdminSchedules`/`createAdminSchedule` use the
+  literal `table_schema='transit'` while `repo/schedules.js` overview/recurring
+  use `'transit.bus'` — matching the original's inconsistent literals.
+- The `GET /schedules/overview` handler's `else if (DEV_MOCK && …)` enrichment is
+  **dead code** in the original (the mock branch returns earlier); it is NOT
+  copied into `repo/schedules.mock.js`.
+
+**End-of-Stage checks:**
+- `grep -rn DEV_MOCK index.js routes/` → clean.
+- `node --check` → passes for `index.js`, all `routes/*.js`, `repo/*.js`,
+  `mock/store.js`, `middleware.js`, `db.js`.
+- `git status`/`git diff` → the only file changes in `transit_api/` are the Stage
+  splits (no stubs or temp files left behind; the parity baseline
+  `index.c-original.js` is only ever copied in from `/tmp/opencode` during runs
+  and removed afterwards).

monitoring_ui/docs/transit_api/README.md

@@ -72,52 +72,54 @@ All endpoints require an `Authorization: Bearer {token}` header.
 
 ### Schedule
 
-Schedules are weekly templates. Each row in `transit.schedules` represents one
+Schedules are weekly templates. Each row in `"transit.bus".schedules` represents one
 departure time for one bus line and one `day_of_week`:
 
 - `1` to `5`: weekdays
 - `6`: Saturday
 - `0`: Sunday
 
-Driver assignments are stored separately in `transit.shifts` with
+Driver assignments are stored separately in `"transit.bus".shifts` with
 `(schedule_id, driver_id)`, where `driver_id` references `workers.users(id)`.
 The current `shifts` shape represents the active assignment. To retain different
 assignments for different calendar weeks, add a `week_start` (or assignment date
 range) column and include it in the unique key.
 
-**GET** `/driver/schedules/daily?date=2026-09-18`
+**GET** `/bus/driver/schedules/daily?date=2026-09-18`
 
-- Returns only weekly schedule templates assigned to the authenticated driver through `transit.shifts`.
+- Returns only weekly schedule templates assigned to the authenticated driver through `"transit.bus".shifts`.
 
-**PATCH** `/driver/weekly-schedules/:scheduleId/status`
+**PATCH** `/bus/driver/weekly-schedules/:scheduleId/status`
 
 - Updates the status of an assigned weekly schedule.
 
-**GET** `/admin/weekly-schedules`
+**GET** `/bus/admin/weekly-schedules`
 
 - Lists weekly templates and their current driver assignments.
 
-**GET** `/admin/shift-drivers`
+**GET** `/bus/admin/shift-drivers`
 
 - Lists drivers from `workers.users` for shift assignment.
 
-**POST** `/admin/weekly-schedules`
+**POST** `/bus/admin/weekly-schedules`
 
 - Creates one template. Body: `{ "busLineId": 1, "dayOfWeek": 1, "startTime": "08:00", "endTime": "09:00", "driverId": 12 }`.
 
-**POST** `/admin/weekly-schedules/bulk`
+**POST** `/bus/admin/weekly-schedules/bulk`
 
 - Creates multiple departures in one transaction. The API derives each end time
   from the selected bus line duration. Body: `{ "busLineId": 1, "dayOfWeeks": [1,2,3,4,5], "startTimes": ["06:00", "06:30", "07:00"], "driverId": 12 }`.
 
-**PUT** `/admin/weekly-schedules/:scheduleId/shift`
+**PUT** `/bus/admin/weekly-schedules/:scheduleId/shift`
 
 - Replaces the driver assignment. Pass `{ "driverId": 12 }` or `{ "driverId": null }`.
 
-The legacy `/admin/schedules` and `/schedule/daily` endpoints remain for older
-clients, but new clients must use the weekly schedule endpoints above.
+The legacy `/admin/schedules` and `/schedule/daily` aliases remain for older
+clients, but new clients must use the `/bus/`-prefixed canonical endpoints
+(`/bus/admin/schedules`, `/bus/schedule/daily`) and the weekly schedule
+endpoints above.
 
-**GET** `/schedule/daily?date=2024-05-05`
+**GET** `/bus/schedule/daily?date=2024-05-05`
 
 - Retrieve daily schedule for driver
 - Response:
@@ -145,14 +147,14 @@ clients, but new clients must use the weekly schedule endpoints above.
 }
 ```
 
-**GET** `/routes/:routeId`
+**GET** `/bus/routes/:routeId`
 
 - Details of a specific route
 - Response: `{ "route": {...} }`
 
 ### Public Schedule Overview
 
-**GET** `/schedules/overview?date=2026-05-06&lineId=1`
+**GET** `/bus/schedules/overview?date=2026-05-06&lineId=1`
 
 - Fetches a date-based overview of scheduled services
 - Weekly templates are selected by `day_of_week` and driver assignments by `shifts`
@@ -160,17 +162,18 @@ clients, but new clients must use the weekly schedule endpoints above.
 - Filters: `driverId`/`chauffeurId`, `stopId`/`busStopId`, `lineId`, `status`
 - Response: `{ "date": "2026-05-06", "summary": {...}, "schedules": [...] }`
 
-The legacy endpoint **GET** `/schedules` remains available for existing clients.
+The legacy endpoint **GET** `/schedules` remains available as a deprecated alias
+for existing clients; the canonical path is **GET** `/bus/schedules`.
 
 Example:
 
 ```bash
-curl "https://transit.xtransit.testinstance.nl/schedules/overview?date=2026-05-06&chauffeurId=12&busStopId=3"
+curl "https://transit.xtransit.testinstance.nl/bus/schedules/overview?date=2026-05-06&chauffeurId=12&busStopId=3"
 ```
 
 ### Navigation
 
-**POST** `/navigation/route`
+**POST** `/bus/navigation/route`
 
 - Save calculated route from OSRM
 - Body:
@@ -191,7 +194,7 @@ curl "https://transit.xtransit.testinstance.nl/schedules/overview?date=2026-05-0
 }
 ```
 
-**GET** `/bus-lines/:busLineId/stops`
+**GET** `/bus/bus-lines/:busLineId/stops`
 
 - All stops of a bus line (for navigation waypoints)
 - Response:
@@ -212,7 +215,7 @@ curl "https://transit.xtransit.testinstance.nl/schedules/overview?date=2026-05-0
 
 ### GPS Tracking
 
-**POST** `/gps/track`
+**POST** `/bus/gps/track`
 
 - Save real-time position
 - Body:
@@ -228,7 +231,7 @@ curl "https://transit.xtransit.testinstance.nl/schedules/overview?date=2026-05-0
 }
 ```
 
-**GET** `/gps/route/:routeId`
+**GET** `/bus/gps/route/:routeId`
 
 - All recorded position points of a route
 - Response:
@@ -250,7 +253,7 @@ curl "https://transit.xtransit.testinstance.nl/schedules/overview?date=2026-05-0
 
 ### Route Status
 
-**PATCH** `/routes/:routeId/status`
+**PATCH** `/bus/routes/:routeId/status`
 
 - Update route status
 - Body: `{ "status": "in_progress" }`
@@ -260,7 +263,7 @@ curl "https://transit.xtransit.testinstance.nl/schedules/overview?date=2026-05-0
 
 All admin endpoints require, in addition to a valid JWT token, that your `userCode` is present in `ADMIN_USER_CODES`.
 
-**POST** `/admin/stops`
+**POST** `/bus/admin/stops`
 
 - Create a reusable stop
 - Body:
@@ -273,7 +276,7 @@ All admin endpoints require, in addition to a valid JWT token, that your `userCo
 }
 ```
 
-**POST** `/admin/bus-lines/:busLineId/stops`
+**POST** `/bus/admin/bus-lines/:busLineId/stops`
 
 - Link an existing stop to a bus line
 - Body: