Field Manual / Systems

Under the hood

The plumbing under the three apps. Auth, the Drizzle schema and PGlite dev DB, the SSE pub/sub, the routes-and-stops catalog, the demo simulator that keeps staging alive, and the imagery pipeline that downloads Unsplash once and serves forever.

Authentication

Email OTP for riders, password for admins

A single user table backs three surfaces. Riders and drivers sign in by email OTP — six digits, 10-minute expiry. Admins use a password fallback because they sign in twenty times a day. Both flows mint the same JWT.

JWTOTPHono

Database

Drizzle + PGlite locally, Postgres in prod

Drizzle ORM with a schema in TypeScript. Locally, the API runs on PGlite for zero-setup dev. In production, the same schema points at a real Postgres connection string.

DrizzlePostgresPGlite

Realtime

SSE pub/sub, no Redis, no socket framing

Vehicles broadcast positions to a server-side pub/sub bus. Every connected client (rider, driver, dispatcher) subscribes via Server-Sent Events. No WebSocket library, no message framing, no Redis — just an in-process EventEmitter and Hono streamSSE.

SSEPub/SubHono

Routes & stops

Schedule as minute-of-day

Every route is a sequence of stops with a scheduledMinuteOfDay field. The schedule is a number between 0 and 1439, not a timestamp — because routes repeat daily and the time-of-day is what matters, not the calendar date.

SchemaRoutesStops

Demo simulator

Vehicles that walk the route

In dev and staging, a background simulator walks each active vehicle along its route's polyline. The pings go through the same `POST /api/driver/ping` endpoint a real driver hits — same code path, same SSE fan-out. The whole product feels live without a human in the seat.

DevSimulationSSE

Imagery

Mapbox tiles, Unsplash photos

Two external sources, both cached aggressively. Mapbox light-v11 powers the admin map. Unsplash powers every hero image — routes, stops, driver portraits, offers. We download once, serve from disk forever.

MapboxUnsplashCaching

Tech Stack

Hono

Drizzle

PGlite

Expo SDK 54

Next 15

Mapbox

Zod