Demo simulator
Vehicles that walk the route
Overview
On API startup in non-production mode, the simulator reads every assignment for today and spawns a worker per active vehicle. The worker walks the route's polyline at the vehicle's nominal speed, pinging the API at the same cadence a real driver would. The result: every screen — rider Today, driver Shift, admin Dispatch — shows a moving vehicle on first load.
How it works
Startup: `apps/api/src/sim/start.ts` reads assignments with status in_progress and dateISO today. For each, it grabs the route's stops, builds a linear interpolation across them, and spawns a setInterval worker.
Each worker computes the current position based on wallClock minus shiftStart and the route's total distance. It clamps to the polyline so the marker never goes off-route.
Pings: the worker calls the vehicles.broadcastLive helper directly (skipping the HTTP boundary) which writes to the ring buffer and emits on the bus. The dispatch, driver, and rider screens see the same data they'd see from a real driver.
Speed: we use a fixed 11 m/s (about 25 mph) so the ETA math feels realistic without burning the route in five minutes.
Disable: setting VINEROUTE_DISABLE_SIM=true in env skips the startup hook entirely. Production sets this by default.
Authentication is bypassed for the simulator — it calls the broadcast helper as a server-internal action, not through the HTTP layer.
Key decisions
Simulator over an empty staging
Staging without live traffic looks dead — the map sits empty, the ETA banner doesn't render, screenshots feel like a wireframe. The simulator means every dev opens the app to a populated, moving world. Bugs are visible, demos are alive, and the design feedback loop is twenty times tighter.
Same endpoint as a real driver
The simulator could have written directly to the SSE bus, skipping the ping handler. We didn't, because we'd lose end-to-end coverage of the actual write path. By hitting the same code as a driver phone, every regression in that path surfaces in dev before it hits production.
Off by default in production
An env flag (VINEROUTE_DISABLE_SIM) gates the simulator off in production builds. We considered a build-time strip, but a flag lets us turn it on temporarily in staging for demos. The default is correct; the override is rare.