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.
Una operación, tres experiencias
Tres portales especializados por rol
El mismo pedido se ve distinto para quien lo despacha, quien lo entrega y quien lo recibe. Selecciona un portal para ver su experiencia.
Portal Admin
Orders (outbound + inbound PO), rutas, clientes, drivers, inventario, atenciones, asistente IA y settings con RBAC.
| ID | Destino | Estado |
|---|---|---|
| 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 SKU bajo el 50% del mínimo · 6 unidades In Transit
Máquina de estados explícita
El pedido nunca está en un estado ambiguo
Cada transición está modelada en el backend. No hay "creo que ya salió": el pedido avanza por estados definidos y la rama de excepción es de primera clase.
Desde on_route / in_transit, rama de excepción:
Inbound (pickup PO): al recoger se registra la orden de compra; al llegar a delivered el stock se reabastece automáticamente. Inventario que se corrige solo.
Integración Shopify / Make
Matching de productos en 4 pasos
Los pedidos entran por una Edge Function con API key. El catálogo externo nunca calza perfecto con el interno, así que el match es una cascada: barato y determinista primero, IA solo cuando hace falta.
SKU exacto
Si el SKU del documento externo coincide con el catálogo, match inmediato.
si falla ↓
Nombre exacto
Sin SKU válido, se intenta coincidencia exacta por nombre normalizado.
si falla ↓
Fuzzy Jaccard ≥ 0.6
Similitud de tokens entre nombres; se acepta sobre el umbral 0.6.
si falla ↓
Fallback IA
Si nada resuelve, la IA decide el producto correcto con el contexto de la factura.
Además, los PDF de facturas se parsean con IA para extraer líneas y cantidades antes de pasar por la misma cascada de matching.
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.