CASE · LOGISTICS & DISTRIBUTION · USA
A last-mile operator that went from paper to an operation proven end-to-end
Three portals, multimedia proof of delivery, an explicit state machine, and AI-powered product matching. This is how we rebuilt the operation of a last-mile logistics operator in the United States.
The process before
An operation that lived on memory and phone calls
Paper routes
Drivers left with a printed sheet. Reordering stops or reassigning a vehicle meant a phone call and a handwritten note.
No proof of delivery
"Did it arrive or not?" was resolved by phone. No photo, no signature, no name of who received it.
Blind inventory
The inventory had no visibility into what was in transit or coming in via pickup. Shortages were discovered when it was already too late.
How we understood it
From the real route to the optimized flow
We modeled the order as a state machine
We defined every transition — including the exception branch — so no shipment ever ends up in an ambiguous state.
We separated the operation into three portals
Admin controls, the driver operates from their phone, and the client self-services. Each role sees only what they need.
We made proof of delivery mandatory
Compressed photos, signature, voice notes, and "Received By" before being able to close the stop. Doubt disappears.
We connected orders and inventory in real time
Shopify/Make enter via Edge Function, matching resolves the product, and stock auto-replenishes on inbound.
One operation, three experiences
Three portals specialized by role
The same order looks different to whoever dispatches it, delivers it, and receives it. Select a portal to see its experience.
Portal Admin
Orders (outbound + inbound PO), routes, clients, drivers, inventory, attentions, AI assistant, and settings with RBAC.
| ID | Destination | State |
|---|---|---|
| ORD-1042 | Brooklyn DC | on_route |
| ORD-1043 | Queens Hub | in_transit |
| PO-0218 | Inbound · Newark | pickup_ready |
| ORD-1041 | Bronx Store | delivered |
Inventory: 2 SKUs below 50% of the minimum · 6 units In Transit
Explicit state machine
The order is never in an ambiguous state
Every transition is modeled in the backend. There is no "I think it already left": the order advances through defined states and the exception branch is first class.
From on_route / in_transit, exception branch:
Inbound (pickup PO): the purchase order is recorded at pickup; on reaching delivered the stock is replenished automatically. Inventory that corrects itself.
Shopify / Make integration
Product matching in 4 steps
Orders come in through an Edge Function with an API key. The external catalog never lines up perfectly with the internal one, so matching is a cascade: cheap and deterministic first, AI only when needed.
Exact SKU
If the SKU on the external document matches the catalog, it is an immediate match.
if it fails ↓
Exact name
With no valid SKU, an exact match on the normalized name is attempted.
if it fails ↓
Fuzzy Jaccard ≥ 0.6
Token similarity between names; accepted above the 0.6 threshold.
if it fails ↓
AI fallback
If nothing resolves it, the AI picks the right product using the context of the invoice.
Invoice PDFs are also parsed with AI to extract line items and quantities before going through the same matching cascade.
What was built
The complete system, not a loose piece
3 role-based portals
Admin (full control), Driver (mobile-first), and Client (self-service), each with its own UX.
Multimedia POD
Multiple compressed photos (≤1280px / JPEG 0.7), digital signature, voice notes, and mandatory receiver name.
AI product matching
4-step cascade: SKU → name → fuzzy Jaccard ≥0.6 → AI fallback. Invoice PDFs parsed with AI.
Auto-replenish inbound
The pickup PO records the purchase order and stock updates automatically upon delivery.
Realtime on Postgres
Triggers + subscriptions: what the driver confirms appears instantly in admin and the client portal.
Granular RBAC module × action
Fine-grained permissions, has_role() SECURITY DEFINER, and 30-day trash with restore.
Development scope
What's underneath
- ▸Explicit state machine: pending → assigned → picked → pickup_ready → on_route → in_transit → delivered, with needs_attention / not_delivered branches.
- ▸Granular RBAC per module and action with has_role() SECURITY DEFINER function and soft-delete (30-day trash).
- ▸Deno Edge Functions with API key for Shopify/Make ingestion and AI-powered invoice PDF parsing.
- ▸Mapbox dark-v11 for routes and stops; reordering in the driver portal.
- ▸Realtime via Postgres triggers + Supabase subscriptions across all three portals.
Outcomes
What changed in the operation
Every delivery is proven: never again a dispute about "did it arrive or not?".
The driver runs the full day from their phone, without paper.
The inventory reflects reality: transit and inbound are no longer blind spots.
Operations stopped being a call center: the client self-services.
YOUR OPERATION IS THE NEXT CASE
Does your last-mile run on phone calls and paper?
We'll show you how we'd model your operation as a system: role-based portals, proof of delivery, and explicit states. Schedule a 30-minute assessment.