Convoy Copilot

Inspiration

Convoy operations become hardest when conditions change mid-mission. A road closure, wildfire, severe weather, vehicle limitation, or cargo deadline can turn a valid route into a dangerous one. Dispatchers must reconcile scattered data quickly while drivers need clear, approved instructions—not another dashboard full of raw alerts.

We built Convoy Copilot to turn live operational evidence into safe, explainable route decisions while keeping a human dispatcher in control.

What it does

Convoy Copilot manages a relief convoy mission from disruption detection through driver acknowledgement.

It can:

• Model missions, vehicles, cargo, routes, restrictions, safe stops, and disruptions as a Jac graph.
• Detect which routes, vehicles, and cargo are affected by a disruption.
• Validate candidate routes against vehicle dimensions, cargo requirements, road restrictions, and risk.
• Compare recommendations from specialist agents and produce an explainable route proposal.
• Incorporate keyless NWS, Caltrans, and NIFC/WFIGS evidence.
• Match hazards to the route corridor and estimated travel window.
• Reject routes only when an authoritative restriction applies—wildfire proximity alone never implies a road closure.
• Require dispatcher approval before changing assignments.
• Present the approved route and next action in a focused driver view.
• Preserve a mission timeline for auditing and replay.
• Fall back to deterministic fixtures when external services are stale or unavailable.

How we built it

The backend is written in Jac and uses nodes, typed edges, walkers, and public functions to represent and operate on the mission graph. Walkers traverse relationships between disruptions, route legs, vehicles, cargo, and safe stops to calculate impact.

Deterministic validation and scoring select safe route candidates before an LLM is allowed to explain the result. The model narrates settled facts; it does not directly mutate the graph or make unchecked routing decisions.

We built the interface with Next.js, TypeScript, Tailwind CSS, and MapLibre. It includes a dispatcher dashboard, route comparison workspace, specialist evidence overlays, mission history, and a mobile-friendly driver assignment view.

The environmental pipeline runs server-side and normalizes:

• National Weather Service alerts, forecasts, and observations
• Caltrans District 6 closures, roadside weather, chain controls, and message signs
• NIFC/WFIGS wildfire incident points and perimeters

Each source has caching, freshness metadata, bounded concurrency, pagination, and deterministic fallback behavior.

Challenges we ran into

One major challenge was keeping the system useful when live government feeds were slow, malformed, throttled, or temporarily unavailable. We solved this with shared cached snapshots, conditional requests, strict timeouts, visible fallback states, and fixture-backed continuity.

Geospatial safety semantics were another challenge. A wildfire near a route is important evidence, but it is not proof that the road is closed. We separated risk signals from authoritative hard restrictions and added deterministic corridor and ETA matching.

We also had to coordinate a fast-moving Jac and frontend codebase. Jac’s syntax and type system differ from both Python and TypeScript, so we relied on compiler guides, frequent jac check runs, and deterministic tests.

Finally, merging independently developed route visualization and live-evidence features required carefully preserving both specialist-agent overlays and environmental GeoJSON layers.

Accomplishments that we're proud of

We are especially proud that Convoy Copilot is more than a chatbot around a map. It has a typed operational model, deterministic safety rules, graph traversal, human approval, and an auditable state-transition workflow.

Other highlights include:

• A complete disruption-to-driver workflow.
• Explainable route acceptance and rejection.
• Multiple specialist recommendations visualized on the map.
• Credential-free live government-data integrations.
• Safe behavior during provider outages and throttling.
• Explicit data freshness, confidence, attribution, and simulation labels.
• Deterministic Jac and Python tests plus a production-validated Next.js build.
• A resettable fixture scenario that remains dependable during judging.

What we learned

We learned that trustworthy agentic systems need a clear boundary between evidence, decisions, and explanations. Agents are most valuable when they help interpret structured facts, while deterministic code enforces safety constraints and humans authorize consequential actions.

We also learned how naturally Jac’s graph model represents logistics. Questions such as “Which cargo is affected by this closure?” become graph traversals rather than fragile chains of database queries.

On the integration side, we learned that public data is not automatically reliable data. Production-ready use requires caching, pagination, freshness tracking, deduplication, attribution, and graceful failure handling.

What's next for Convoy Copilot

Next, we want to:

• Add more Caltrans districts and nationwide road-condition providers.
• Incorporate CHP incidents and travel-time feeds.
• Support continuous GPS updates and moving ETA windows.
• Improve corridor matching with production geospatial indexing.
• Add persistent provider snapshots and historical hazard comparisons.
• Expand specialist agents for fuel, maintenance, security, and safe-stop planning.
• Add authenticated multi-user operations and role-based approvals.
• Deliver proactive driver notifications and acknowledgement tracking.
• Deploy the complete Jac service and frontend for real-world pilot missions.

Built With

• jac
• next.js