DOT Permit Routing | Rafa Chavantes

Context

In the US, trucks hauling oversize or overweight loads need a permit from each state they cross. The permit dictates the exact roads the truck may use, and every state issues it through a different system, in a different format, as a dense PDF built for compliance officers, not drivers.

The problem

Turning that PDF into an actual route was manual work: someone reading the permit line by line and rebuilding it in a maps app. Slow, error-prone, and high-stakes. A wrong route can mean a bridge strike, a fine, or a revoked permit.

What I owned

The entire system, solo: from the first research spikes through architecture, implementation, and production reliability. Payment and ordering flow, the AI pipeline, the routing logic, the review tooling, and the tests.

How it works

Permit to navigation, step by step

Permit PDFinput→Detect state systempattern matching→Read & interpretAI agent→Route geometrydeterministic code→Score & verifyrules + review→Navigation linkdriver-ready

■ coral = deterministic code I wrote · ■ green = AI, kept only where interpretation helps

An AI agent (a tool-calling loop with geocoding, routing, and validation tools) reads the permit and proposes the route. Candidate routes are then scored by deterministic rules: how far the route deviates from the permitted distance, whether it stays inside a corridor around the permitted roads, whether it ever leaves the state. Low scores never reach a driver. A human reviews and can override waypoints before anything is sent.

Self-serve order flow: upload a permit PDF, pay, receive the processed route — The customer-facing flow: upload a permit PDF, pay, receive the route (production screenshot, brand anonymized)

Key decisions

Exact geometry comes from the source, not the model. The AI kept producing subtly wrong routes, U-turns around off-ramps that no amount of prompt iteration fixed. I recognized this wasn't a prompting problem: exact geometry can't depend on a probabilistic model. Where states embed a QR code in the permit, my code now decodes it (computer vision) and fetches the official route from the state's own system.
Benchmark before committing. Before building the production pipeline, I ran a structured experiment: a linear single-pass pipeline vs. an agentic loop, across five different AI models, on the same set of real permits, with a written results report. The agentic approach won on complex permits and became the architecture.
Guardrails are code, not prompts. Score floors, corridor checks, state-boundary guards, and per-job API budgets are all deterministic. The AI proposes; the rules dispose.
A human gate before delivery. Staff review low-confidence routes with a live processing feed and a waypoint editor. Failures are logged and surfaced, never silently retried.

Result screen for a Texas permit: both routing providers score 92 and the approved route is drawn on the map — A processed Texas permit: both routing providers score 92 and the approved route is drawn end to end (production screenshot, brand anonymized; the permit document panel is hidden because it holds client data)

Verification & reliability

The system carries roughly 280 automated test files: unit and end-to-end tests on the web side (Playwright), a full test suite on the Python pipeline (route simplification, state-boundary logic, error-recovery loops, output contracts), database security tests, and CI on every change.

Internal jobs dashboard listing processed permits with status, score, carrier, and state — The internal operations view: every processed permit with its status, score, and state (production screenshot, brand anonymized)

Outcome

In production today with a self-serve ordering flow and payment, plus an internal operations dashboard for the team. Drivers receive exact, trustworthy navigation built from permits that no two states format alike.

Management dashboard with order stats, sales, and items needing review — Management dashboard: order volume, sales, and what needs attention (production screenshot, brand anonymized)

What I'd improve today

I spent weeks trying to prompt my way to reliable geometry before moving it into deterministic code. I'd make that call earlier now. Next on the list: extending official-route extraction to more state systems.

NDA note: the client is not named, and visuals are recreated with fictional permit and route data. The architecture, decisions, and outcomes described here are real.