HackTruck — The intelligence layer for small fleet dispatchers

Inspiration

Small and mid-size trucking fleets (5–50 trucks) move the backbone of the American economy — and they're still running on phone calls, text messages, and spreadsheets. The Trucker Path brief put a face on this: meet Maria, a dispatcher running a 20-truck fleet out of Phoenix, and John, one of her drivers. Maria's Monday starts at 7am with 18 loads to cover and 20 drivers scattered across the Southwest. She spends the first 90 minutes of her day texting each driver to ask "where are you, how much HOS is left, are you good to run?" — then picks loads from memory and finds out about breakdowns only when a customer calls asking where their freight is.

The product has the inputs — GPS pings, HOS clocks, uploaded BOLs, fuel receipts. What's missing is the layer that turns those inputs into decisions. That's what we built.

What it does

HackTruck is an AI-native fleet operations assistant — a web console for dispatchers layered on top of the Trucker Path NavPro data model. It addresses three of the five gaps from the brief:

Smart Dispatch — When a load comes in, one click asks our /api/match-load endpoint to rank the top 3 drivers for it. An LLM (OpenAI gpt-4o-mini) scores every driver by equipment fit, HOS remaining, distance-to-pickup, lane familiarity, active trips, and open alerts, and returns a ranked shortlist with a 1–2 sentence "why this driver" reason for each. A deterministic heuristic fallback kicks in when the API is unavailable, so the demo never breaks.
Proactive Alerts — A live map with Mapbox + OpenWeather Maps 2.0 tiles shows every truck, every load, and weather hazards along the lane. A timeline scrubber lets Maria preview weather windows hours ahead. A 511-style situation feed (demo data) surfaces incidents before the customer calls.
Comparison Tray & Cost Intelligence — Side-by-side compare the top-ranked drivers on deadhead miles, HOS remaining, ETA, and cost, with the best metric on each row highlighted so the right call is obvious in 5 seconds instead of 5 phone calls.

The demo is live and interactive — judges click a load, see the AI pick three drivers, inspect the map, scrub the weather timeline, and assign.

How we built it

Framework: Next.js 16 (App Router) + React 19 + TypeScript, Tailwind 4
Map: mapbox-gl / react-map-gl with custom driver and load markers, animated polyline progress, and a dispatch-pressure heatmap overlay
Weather: OpenWeather 2.5 current conditions + Maps 2.0 forecast tiles for the timeline scrubber, with a server-side key verification step so missing/invalid keys fail gracefully at page load
AI: POST /api/match-load — builds a structured payload (drivers, load, vehicles, trips, alerts), sends it to OpenAI with a JSON-only response format, validates that driver IDs returned exist, and fills any gaps from a heuristic scorer
State: three React context providers — DispatchProvider, MatchLoadProvider, FleetHoverProvider — keep the map, sidebar, comparison tray, and toast in sync without a heavyweight store
Demo data: a backend-in-memory DB (lib/backend-db.ts), 511 incident fixtures, hardcoded weather events, and a simulation clock so the whole thing runs locally without a backend

Challenges we ran into

Next.js 16 is not the Next.js of our training data. App Router conventions, the new Turbopack/webpack split, and React 19 server components forced us to read the docs before every non-trivial file.
Making the LLM trustworthy for dispatch. Early prompts hallucinated driver IDs. We fixed it by (1) passing the full driver roster in the payload, (2) forcing response_format: json_object, (3) filtering returned IDs against the real roster, and (4) topping up from the heuristic scorer when the model returns fewer than 3 valid rows.
Weather tile layering. OpenWeather Maps 2.0 tiles needed to render under driver markers but above the base style, without nuking Mapbox road labels. Took a few iterations on the sprite/layer order.
Keeping the comparison tray honest. Highlighting "best metric" green is easy to get wrong when units differ (miles vs. hours vs. dollars). We normalized per-column before picking a winner.

Accomplishments that we're proud of

A dispatcher can go load → top-3 AI picks → compare → assign in under 15 seconds, on a live map, with weather-aware context. That's the headline demo.
The AI layer degrades gracefully — no OpenAI key, no problem; the heuristic ranker keeps the product demo-able offline.
The UI feels like a real dispatch console, not a hackathon toy: per-driver HOS, map trip routes, toast notifications, driver/load detail panels, and a timeline scrubber.

What we learned

The Trucker Path brief said it clearly: "Show the intelligence, not just the data — decisions, not dashboards." Every time we were tempted to add another chart, we asked instead: what decision does Maria make differently because of this? That filter cut the scope in half and made the demo sharper.

We also learned that for a 5–50 truck fleet, the win isn't a fancy optimizer — it's eliminating the 20 morning text messages. The LLM isn't doing anything a great dispatcher couldn't do with perfect memory; it's giving Maria back her first 90 minutes.

What's next for HackTruck

Billing & Doc Auto — auto-reconcile BOL / POD / fuel receipts into an invoice packet the moment a load is marked delivered
Safety & Compliance — early-warning flags for HOS patterns, missed inspections, and fatigue signatures before they become an audit
Driver-side handshake — push the dispatcher's pick to John's phone so the assignment, route, and rate con land in one tap
True cost-per-mile rollup — per-driver, per-lane, per-corridor, so Maria can finally answer "is our margin loss deadhead, fuel, or HOS stops?"