Back to README · See also Architecture & Design · Implementation Plan · Booking Architecture Spec
SevaRath is an internal EV transportation booking system for the Shantivan / Brahma Kumaris headquarters campus. It provides an Uber-like request → match → ride workflow for campus EVs, with no payment, fare, surge, or commercial transaction logic.
This document defines what the system must do and the domain rules it must enforce. For how it is built (stack, modules, APIs, infra), see architecture.md.
| Role | Description |
|---|---|
USER |
Campus resident/visitor requesting a ride |
DRIVER |
Approved operator of a campus EV |
ADMIN |
Manages drivers, vehicles, users, and operations |
OPERATOR |
Lightweight operational role (dispatch oversight, no full admin rights) |
Role-based access control (RBAC) applies to every API and WebSocket channel - see architecture.md §8 Security & Identity.
- Sign in (OTP or SSO per architecture.md §8)
- View current GPS location
- Select pickup - current GPS, map tap, or a predefined campus location
- Select destination - same options
- Request an EV (
POST /api/v1/rides) - View live request status (
SEARCHING_DRIVER→DRIVER_ASSIGNED→ …) - View assigned vehicle/driver details
- Track the EV live on a map
- View route/ETA to pickup, then to destination
- Cancel the request while permitted by ride state
- Mark trip complete (system-confirmed, not client-asserted)
- View ride history
- Sign in
- Toggle online/offline (
AVAILABLE⇄OFFLINE) - Share current location at a tunable interval (see §6)
- Receive ride requests with a bounded response window (default 15s)
- Accept/reject a request
- Navigate to pickup
- Mark arrived, then start ride
- Navigate to destination
- Complete ride
- View ride history
- Driver management (create, approve, suspend)
- User management
- Vehicle management (create, assign, retire)
- Driver ↔ vehicle assignment
- Driver availability monitoring
- Active ride monitoring
- Ride history / audit trail
- Operational dashboard (see §9)
Admin does not need to ship in the first mobile release but is part of the target architecture from day one (Admin is the first consumer of the React/shadcn frontend - see architecture.md §7).
Backed by the open-source MapLibre + Valhalla stack - see architecture.md §8 for implementation detail.
- Route line plotted on the map
- Moving vehicle marker, driven by live location updates
- Current GPS position of the viewing device, shown distinctly from the vehicle marker
- Map rotation that follows vehicle heading
- Turn-by-turn instructions (Driver app, primary; en-route display on User app)
- Distance to next maneuver
- ETA, recalculated as the ride progresses
- Voice instructions for turn-by-turn guidance
- Automatic rerouting when the driver deviates from the active route
- Route progress (distance/percentage traveled)
- Pickup and destination markers
- Custom EV/organization icons for markers
- Custom campus roads and POIs rendered as a map overlay, and routable by EVs even though they don't exist in public map data
- Specific areas can be dynamically included/excluded from EV routing (e.g. a closed plaza or a restricted zone) without a map rebuild - see
campus_restricted_zonesin §7
Deliberately excluded from the initial system - do not design around these:
- Payments, fare calculation, surge pricing, wallets
- Driver ratings, tips, promotions
- Public/self-service driver registration
- Multi-city support, customer-support marketplace
- Dynamic pricing or advanced dispatch optimization (ML-based ETA, batching, etc.)
- Building a routing/map-matching engine from scratch - use Valhalla (open-source, self-hosted) for route calculation and maneuver narrative; the apps implement only the navigation UI, voice playback, and off-route detection, not their own routing algorithm (see architecture.md §8)
Ride state is server-authoritative. No client may set ride state directly; the backend validates every transition.
REQUESTED
→ SEARCHING_DRIVER
→ DRIVER_ASSIGNED
→ DRIVER_EN_ROUTE_TO_PICKUP
→ DRIVER_ARRIVED
→ RIDE_STARTED
→ DRIVER_EN_ROUTE_TO_DESTINATION
→ COMPLETED
Terminal/alternate states:
CANCELLED_BY_USER
CANCELLED_BY_DRIVER
CANCELLED_BY_SYSTEM
NO_DRIVER_AVAILABLE
Invariant: two drivers must never be assigned to the same SEARCHING_DRIVER ride. Assignment is a single atomic, transactional operation on the backend (see architecture.md §4 Dispatch for the locking strategy).
Every transition emits a ride_events audit record (see §7).
- Driver apps push location updates on a tunable cadence: ~3–5s while moving, ~10–15s while stationary (tune after field testing).
- Current location is transient - it lives in the cache layer (Redis), not as a row-per-update in Postgres (see architecture.md §9.2).
- Updates carry
latitude, longitude, heading, speed, accuracy, timestamp. - Updates with
accuracyworse than a configurable threshold (default 100m) are treated as low-quality and must not silently overwrite a good last-known position. - Historical location is only persisted if there's a defined operational need (safety/incident investigation) - define retention policy before implementation; default is no permanent raw-GPS history.
Authoritative entities (PostgreSQL via Drizzle - see architecture.md §5):
| Entity | Purpose |
|---|---|
users |
Person record: name, mobile, email, role, status |
drivers |
Driver profile linked to a user, driver code, status, current vehicle |
vehicles |
EV record: code, registration, type, capacity, status |
rides |
A single ride request through completion/cancellation, with full timestamp trail |
ride_events |
Append-only audit log of every state transition (RIDE_REQUESTED, DRIVER_ASSIGNED, DRIVER_REJECTED, …) |
campus_locations |
Named, typed campus points (gates, buildings, EV stops, etc.) usable as pickup/destination |
campus_roads |
Campus-private road/path geometry not present in public OSM data - rendered as a map overlay and merged into the Valhalla routing graph so EVs can be routed over it (see architecture.md §8.2) |
campus_restricted_zones |
Polygons (+ active flag, reason) that EV routing must avoid - passed to Valhalla as exclude_polygons per request, toggleable without a map rebuild |
campus_locations.type ∈ GATE, BUILDING, OFFICE, RESIDENCE, DINING, PARKING, EV_STOP, MEDICAL, RECEPTION, OTHER.
Field-level schema lives in architecture.md §5 as Drizzle table definitions, not duplicated here.
| Scenario | Required behavior |
|---|---|
| No driver available | Ride → NO_DRIVER_AVAILABLE; user sees a clear retry message |
| Driver rejects | Automatically offer to next nearest available driver |
| Driver doesn't respond in time | Timeout → move to next driver |
| User cancels | Notify assigned driver, release vehicle back to AVAILABLE |
| Driver cancels | Ride returns to dispatch / SEARCHING_DRIVER |
| Network disconnect (driver) | Keep local UI state; do not assume server-side success; sync on reconnect |
| GPS unavailable | Show explicit error; never report stale coordinates as current |
Minimum viable dashboard surfaces:
- Available / busy / offline EV counts
- Live campus map with EV positions
- Active requests list with current state
- Ride history / search
The first release is successful when this full workflow is reliable end-to-end:
Login → select pickup/destination → request EV → nearest available driver notified
→ driver accepts → user sees driver + live position → driver arrives
→ ride starts → live tracking during ride → ride completes → appears in history
These requirements come from sevarath-booking-architecture-spec.md and apply once Phase 4 (Booking & Dispatch) begins - see architecture.md §4.3 and §6.2 for the implementation mechanism.
Clients (mobile, driver app) may retry a request after a timeout without knowing whether it succeeded server-side. The following commands must be idempotent via a client-supplied Idempotency-Key header:
POST /api/v1/rides (create)
POST /api/v1/rides/:id/accept
POST /api/v1/rides/:id/cancel
POST /api/v1/rides/:id/start
POST /api/v1/rides/:id/complete
A retried request with the same key and same requesting user must return the original result, not create a duplicate ride or re-apply a transition.
| Scenario | Required behavior |
|---|---|
| Driver loses network | Ride remains in Postgres; driver reconnects and GET /api/v1/drivers/pending (or equivalent) recovers any pending offer. |
| User loses network | Ride continues server-side; user reconnects and GET /api/v1/rides/:id resynchronizes current state. |
| WebSocket server restarts | Clients reconnect and resynchronize via REST; no state is assumed from the socket alone. |
| Two drivers accept simultaneously | Exactly one atomic UPDATE ... WHERE status = 'SEARCHING_DRIVER' succeeds; the other receives RIDE_ALREADY_ASSIGNED. |
| User submits the same ride request twice | Idempotency-Key prevents a duplicate ride row. |
| Event/notification delivery fails | Ride state is already persisted; the outbox event remains unpublished and is retried - it is never lost. |
- A user can create a ride and it is persisted before any notification is attempted.
- Only one driver can ever be assigned to a given ride (verified by a concurrency test, not just code review).
- Ride state is authoritative in PostgreSQL; a dropped WebSocket connection never loses it.
- Reconnection restores current ride state via REST.
- Ride lifecycle events are published reliably via the Outbox (architecture.md §4.3), surviving a broker/worker outage.
- Duplicate client requests (same
Idempotency-Key) are handled safely for every command in §11.1. - Every ride state transition and the failure scenarios above have automated tests.