How to build a live logistics dashboard: a simulated fleet, MapLibre and one source of truth

What it is

Wayline is a logistics admin for Next.js 16, React 19, Tailwind CSS 4 and shadcn/ui: a live map of trucks on real roads, an exceptions inbox with one-click fixes, a route planner, a dispatch board, orders, shipments with proof of delivery, fleet, inventory, warehouses and reports — 76 pages that all read the same data. There is no backend. A whole regional delivery company (four warehouses in New York and New Jersey, 34 vehicles, 36 drivers, 24 clients, 120 products, 75 days of history and 29 routes on the road today) is generated in the browser around the moment you open it, and its day plays out in real time. The live demo is at wayline.upfork.dev.

This article is for anyone — person or AI — about to build a dashboard like this. It goes through the architecture in the order you'd build it, shows the real code for each hard part, and puts every surprise we hit right next to the part where it happened, with the fix.

The architecture in four pieces

Each piece has one job, and nothing on screen is stored state:

1. A generator builds the company from a fixed seed and a timestamp ("now"): warehouses, vehicles, drivers, clients, history and today's routes.
2. A clock advances simulated time (×1, ×5, ×20 or paused). It ticks once a second; the map interpolates between ticks every frame.
3. Selectors compute what every screen shows — a route's progress, a vehicle's position, each KPI, each exception — as pure functions of the data and a time t.
4. A change log records what the user does (confirm an order, reassign a stop, receive a purchase order) as mutations replayed over the generated data, with Undo.

Because everything is a function of (data, t), "live", "replay the last four hours" and "what last week's report says" can't disagree: they are the same functions called at different times.

1. Generate the company around "now"

A demo that opens on a finished, quiet day is a bad demo. So the generator doesn't put today's routes at fixed clock times: it places them relative to now. Some trucks left an hour ago, one is 25 minutes behind on the expressway right now, a refrigerated truck crept above 4 °C a quarter of an hour ago, two products ran out at one warehouse. These story beats are constants in the generator, and a test checks each one.

Outside the network's operating hours the demo pins "now" to 11:20 local time, so there is always an operation in progress:

Everything else is deterministic: one seeded random generator, forked per concern (so adding a field to vehicles doesn't reshuffle every order), IDs given out in time order at the very end, and the same now gives the same company. A test generates it twice and compares.

The network runs on New York time whatever the viewer's zone, so every "today", delivery window and chart bucket goes through a time-zone conversion — hundreds of thousands of them while 75 days of history are generated. zonedSlow() is the plain Intl.DateTimeFormat#formatToParts conversion; everything else uses a cached offset:

2. Make the data tell the truth, and test it

The promise of a template like this is that every number agrees with every other: the KPI on the dashboard, the badge in the sidebar and the row in the table. That only holds if the generated data is relationally valid, so the generator has its own tests:

• every order points at a real client and one of that client's own delivery sites;
• shipments and route stops reference records that exist;
• on-hand stock equals the sum of the stock ledger everywhere — except one deliberate discrepancy, which the Reconcile screen is there to find;
• no stock balance ever goes negative, and nothing in the ledger happens in the future;
• the dormant client really has no orders in 60 days;
• the story: the delayed truck is 24–26 minutes late with three stops at risk, one warehouse is at 91 %, one delivery failed today, one document expires in six days.

3. A route's day as a pure function of time

A route is a list of segments: drive to stop 1, dwell there, drive to stop 2 and so on, with a 30-minute break after the first stop that finishes past the driver's break time, and an optional drive back to the warehouse. Delays are events: at time a, m minutes of delay begin, spread over s minutes (a jam on the expressway). The delay accumulated by time t is

D(t) = Σ m · min(1, max(0, (t − a) / s)) (minutes)

and the vehicle's position in its plan is the plan-equivalent time τ = t − D(t). Finding where a route is reduces to finding the segment that contains τ:

The ETA of a future stop goes the other way: find the real time t' at which τ reaches the stop's planned time p, that is t' − D(t') = p. Iterating x ← p + D(x) converges in a few steps because D grows slower than time: its slope is the slowdown rate, capped at 0.95. While a jam is in progress, the same rate slows the vehicle on the map, so the delayed truck's inspector shows a crawl (4 mph when we recorded the demo).

Because all of this is a function of t, the map's "Replay last 4 h" is the same code with an older t, and the route page, the driver app, the customer's tracking page and the dispatch board all show the same ETA.

4. Trucks on real roads, with no routing calls at runtime

Road geometry is computed once, at build time, with OSRM (npm run geometry): every route leg, every warehouse-to-site pair and the lanes between warehouses, with steps=true so each step's duration and road name come back. It's stored as encoded polylines with step breakpoints; is 170 KB. At runtime a leg becomes vertices with cumulative metres and cumulative free-flow seconds , so "this fraction of the leg's time" maps to a point with a binary search on :

5. Drawing 34 vehicles at 60 frames a second

Vehicles are DOM markers, not a symbol layer: each one is a button with a glyph, a heading wedge, a status ring, a label and a delay badge, and it can take keyboard focus. Every animation frame moves them to their position at the interpolated simulation time:

simTime = baseSim + (performance.now() − baseReal) × speed

The expensive parts don't run every frame. Each vehicle's status (its colour family, label and delay) is recomputed once a second; route lines (driven and ahead) are GeoJSON sources updated once a second; below zoom 10.3, nearby vehicles are clustered in screen space twice a second — a greedy pass that groups markers within 44 px — and each cluster shows its members' status mix as a conic-gradient ring.

6. Exceptions: rules, stable IDs and one-click fixes

The exceptions inbox is a rules engine run over the data at now: delayed routes, deliveries whose ETA passes the promised window, refrigerated loads above range, stock-outs with orders waiting, expired compliance documents, late inbound trucks, warehouses over 90 %, approvals and review backlogs. Each rule returns an exception with a severity, the records involved, a place on the map, a due time and a suggested fix:

The suggestion is computed, not canned. For deliveries at risk, the rule looks for the nearest vehicle of the same class (no bikes for pallets, no refrigerated trucks for dry freight) that is on the road, not itself late, with at least 150 kg spare, and words it: "Reassign ORD-6858 to VAN-012 — 6.4 km away with 989 kg spare; saves about 21 min."

The important design choice is the ID. Exceptions are recomputed every 15 seconds of simulated time, so their IDs are derived from what they are about (EX-SLA-${route.id}), and what the user did with them — acknowledged, assigned, snoozed until a time, resolved — is stored separately, keyed by that ID, and merged in:

A snooze ends by itself when now passes it, and an acknowledgement survives the rule firing again.

7. One source of truth for every number

Every metric lives once, in lib/data/selectors/, and every screen calls it: the dashboard tile, the sidebar badge, the report chart and the CSV export. Each metric's definition sits in a tooltip next to it.

That rule was learned the hard way:

8. Writes, Undo, and a mock API you can swap out

Every write goes through lib/api.ts (and its siblings lib/api-fleet.ts, lib/api-inventory.ts, lib/api-network.ts), which behave like a real API. The core: it applies the change at once (optimistically), waits a moment, sometimes fails on purpose (add ?fail=1 to the URL) and then rolls back, and offers Undo on success:

A mutation is a small serialisable record ({ t: "order.status", at, id, to }), and the store keeps the list in localStorage and replays it over the generated company on load. Records the user creates get IDs from 90001 up, so they never collide with generated ones. To connect a real backend, keep the function names in the lib/api*.ts files and make them call your server; the screens never touch the store's internals.

9. Themes that reach the map

Colours are CSS variables in oklch; presets are [data-preset] blocks; the user's choice is a cookie the root layout reads, so the server renders the right theme on the first paint. Blue is the default; the neutral greys take a hue variable (--nh) from the preset, so a green theme doesn't sit on blue-grey surfaces.

10. Shipping it

Three more surprises came while preparing the release, the screenshots and the deploy:

Make it yours

• Your data: keep the selectors and replace the generator with your API. docs/BACKEND.md explains the swap; each screen only calls the lib/api*.ts functions and the selectors.
• Your map: point NEXT_PUBLIC_MAP_TILES_URL and NEXT_PUBLIC_MAP_GLYPHS_URL at your own tiles. For your own sites and routes, edit lib/data/network.ts and run npm run geometry (point it at your own OSRM with OSRM_DRIVING and OSRM_BIKE).
• Your brand: change DEFAULT_UI.preset in lib/theme.ts and the signal colours on :root in app/globals.css; set buyUrl to null in lib/site.ts to remove the demo's "Get Wayline" button.
• Your rules: an exception is one function returning OpsException objects with a stable ID; add yours in lib/data/selectors/exceptions.ts and the inbox, the map's alerts rail and the notifications pick it up.

The fastest way to see all of it is the live demo: open the live map, click TRK-208, then the Exceptions inbox, and add ?speed=20 to any address to watch the day go by.