Dispatcher-focused Next.js 14 App Router app for route planning, fleet operations, exception management, and assignment workflows.
The product now has two primary surfaces:
/keeps the existing map and route-planning workflow intact./reportsis the dispatcher HQ dashboard with KPI filtering, urgent actions, smart to-do, fleet map preview, trip/load/driver drill-downs, route comparison, detention handling, safety/compliance, and docs/billing reconciliation.
/copilot no longer exists as a standalone product surface. It now redirects to /reports, and the useful CoPilot logic has been folded into the new operations dashboard.
- Next.js 14 App Router
- Tailwind CSS 3.4
- Leaflet map stack with existing provider toggle (
osmorhere) - InsForge for operational data
- Gemini via
@ai-sdk/googlefor explainability and assistive flows - Vitest + Playwright for verification
cp .env.example .env.local
npm install
npm run devThe app runs on http://localhost:3030.
| Variable | Purpose |
|---|---|
NAVPRO_API_BASE_URL |
NavPro API base URL |
NAVPRO_API_BEARER_TOKEN |
Server-only NavPro bearer token |
NEXT_PUBLIC_INSFORGE_URL |
InsForge project URL |
NEXT_PUBLIC_INSFORGE_ANON_KEY |
InsForge anon key |
GOOGLE_GENERATIVE_AI_API_KEY |
Gemini API key |
GEMINI_MODEL |
Optional Gemini model override. Defaults to gemini-2.5-flash-lite |
NEXT_PUBLIC_MAP_PROVIDER |
osm or here |
NEXT_PUBLIC_HERE_API_KEY |
HERE tile key when using HERE tiles |
The dispatcher dashboard is intentionally demo-first when the expanded InsForge schema is not available yet.
Live modeis used when InsForge is configured and the backing schema/data are present.Demo modeis used when the live stack is missing or incomplete. The UI keeps the same contracts and behavior, and interactions persist locally in browser storage so the dashboard remains fully interactive.
Current implementation details:
/reportsfetches the dispatcher HQ contract from/api/dispatcher-hq.- The returned snapshot is seeded with realistic scenario data for loads, drivers, trips, alerts, docs, detention, repair, and last-mile guidance.
- Task completion, alert acknowledgement, document review state, and demo assignments persist locally.
- The dashboard UI clearly labels demo/live state and last refresh timestamp.
The main dispatch workflow is:
- Open
/reports. - Use the KPI strip, urgent action band, or smart to-do board to find the next operational issue.
- Open a load from the load board and choose
Assign driver. - The app navigates to
/with dispatch context in the URL. - On the map page, route options are calculated using the existing route-planning flow.
- After a route is chosen, ranked drivers appear in dispatch mode with deterministic readiness scoring.
- Assigning a driver writes the result back to the shared demo state and returns the dispatcher to an immediately updated Reports dashboard.
This keeps a single route-planning product instead of creating a second planner inside Reports.
The expanded schema lives in schema.sql.
It extends the original model with dispatcher OS entities including:
vehiclestripstrip_stopstrip_eventsroute_plansroute_optionsdriver_readiness_scoreshos_snapshotseld_eventsmaintenance_eventsrepair_shopsrepair_estimatesdriver_incidentssafety_scorescompliance_eventslaw_change_alertsroad_condition_alertsmarket_alertsdispatcher_tasksai_recommendationsdriver_notificationsdispatcher_notificationsdocument_requirementsload_documentsinvoice_draftsinvoice_reconciliationdetention_invoice_draftscustomer_notificationsfacility_entry_pointsfacility_entry_imagesfuel_partner_locationsfuel_price_snapshotsdownstream_load_linksassignment_audit_log
The seed section includes the named scenario pack coverage used by the new Reports experience, including Patel urgent assignment, Ramirez fuel/HOS pressure, Nguyen delay, Chen ELD issue, Williams billing blocker, Martinez breakdown, Okafor relay, Reed downstream tradeoff, excessive detention, law-change alerting, market surge, and last-mile entrance guidance.
npm run dev
npm run build
npm run start
npm run lint
npm test
npm run test:browserThe implementation was validated with:
npm run build
npm test
npm run test:browser- Tailwind stays on
3.4.x. - The map tab remains the full route-planning workspace.
- The Reports dashboard uses production-shaped states: loading, empty, error, demo/live, drill-downs, and inline actions.
- Gemini enhances explanations and prioritization, but deterministic scoring and route gating remain the source of truth.
- Seeded last-mile image references live under
public/facilities.