Operator-App Routes
When AI Ops is enabled on the Enterprise tier, technicians see a new Route tab in the operator-app, sitting between Customers and Operations. This tab is where the day's swap + rebalance stops live.
Tab visibility
The Route tab appears for any user with the Service Tech role on a subaccount with ai_ops_tier='enterprise'. If the tech belongs to multiple subaccounts, the tab shows the route for the currently-selected subaccount.
Today's route
Opening the tab calls GET /api/operator/swap-routes/today. The response is the technician's planned or in-progress route for the current shift, with its ordered stops.
The screen renders:
| Element | Purpose |
|---|---|
| Route summary header | Total stops, total distance, estimated minutes, shift end time |
Accept route modal (first open of a planned route) | Map preview + "Accept today's route?" prompt |
| Stop list | Ordered cards, one per stop, with sequence number and action chip |
| Mid-stop UI | Current stop highlighted with ETA countdown |
Accepting a route
When a route is first created, its status is planned. The tech must Accept it to start work. Accepting:
- Flips the route status to
in_progress. - Triggers the auto-maintenance rule: every pickup-stop vehicle is set to
maintenanceto prevent rider grabs. - Locks the route — further re-planning won't reshuffle stops once accepted.
If the tech doesn't accept, the route stays planned and the auto-maintenance rule does not apply.
Stop cards
Each stop card shows:
- Sequence number (1, 2, 3 …)
- Vehicle short ID (e.g.
VH-042) - Address (geocoded from the vehicle's last GPS, or hex centroid for dropoffs)
- Action chip — Pickup / Dropoff / Swap, color-coded
- ETA — solver's estimate for arrival
- Time window remaining — seconds until
time_window_end
Two buttons per card:
- Start nav — opens a deeplink to native maps (Apple Maps on iOS, Google Maps on Android) with the stop's coordinates.
- Complete stop — calls
POST /api/operator/route/[id]/complete-stopwith the stop ID, completion timestamp, and an optional note.
State machine per stop
A stop moves through these states in the UI:
- Upcoming — gray. Not the current target.
- On the way — yellow. This is the next stop in sequence.
- Arrived — blue. The app detected the tech is within ~30 meters of the stop.
- Completed — green.
completed_atis set.
The "Arrived" detection uses background geolocation when available. If geolocation is denied, the tech can manually tap "Mark Arrived."
Offline queue
The operator-app is built for spotty connectivity. If a tech taps Complete stop with no network:
- The event is queued in AsyncStorage with the stop ID, completion timestamp, and any note.
- The UI immediately marks the stop as completed locally.
- A queue indicator appears at the top of the Route tab: "1 pending sync."
- On the next focus event, and every 60 seconds in the background, the queue is flushed against
POST /api/operator/route/[id]/complete-stop.
This means a tech can complete an entire route through a dead-zone subway tunnel and have everything sync once they come back up.
Completing the route
When the last stop is completed, the route's status automatically flips to completed. The tech sees a summary screen with:
- Stops completed (e.g. 14 of 15)
- Total distance traveled (vs. solver estimate)
- Total time on shift
- Estimated revenue uplift (rolled up from the accepted recommendations' projected lift)
If any stops were missed, they re-open as recommendations for the next route or the next tech.
Abandoning a route
Sometimes routes can't be finished — the van breaks down, the tech is sick, weather goes bad. Tapping Abandon Route opens a modal asking for a reason, then calls POST /api/operator/route/[id]/abandon.
On abandon:
- Route status flips to
abandoned. - All vehicles still in
maintenancebecause of the auto-maintenance rule are reverted toavailable. - Any incomplete recommendations attached to the route's stops are re-opened (status back to
open) so the next solver run can re-route them.
Permissions
| Role | Route tab visible | Can complete stops | Can abandon |
|---|---|---|---|
| Service Tech | yes | yes (own routes only) | yes (own routes only) |
| Fleet Manager / Admin | yes (sees all techs) | no | yes (any route) |
| Viewer | no | no | no |
What's not in the screen
- Editing route order. The tech follows the solver's sequence. If the route is wrong, abandon it and re-plan from the dashboard.
- Adding stops on the fly. Mid-shift additions require operator confirmation through the dashboard.
- Multi-route support. One tech, one route per shift. If a tech needs to span two routes, schedule them as two shifts.
Related
- Technician routes — how routes are built and the auto-maintenance rule.
- Rebalance recommendations — the source of pickup/dropoff pairs.