Handbook

Appearance

System At A Glance ​

What this chapter covers ​

This chapter follows one signal end to end — from the tracker on a truck to the map an owner reads and the alert that reaches their phone — and then names the four data planes that the rest of the handbook is organised around. The planes are the book's mental model: once you can place any feature in one of them, the whole system fits together.

The picture ​

Read it this way

Ingress accepts and normalizes, the queue absorbs delay, the engine interprets, and the surfaces read the result. Tenant ownership is resolved in the engine, never trusted from the queue payload.

Following the signal ​

A truck's tracker emits a reading — a position, or a position-less status frame carrying voltage, ignition, or fuel — and hands it to Flespi, the gateway that speaks to the whole tracker fleet on Korido's behalf. Flespi delivers it to Korido as a webhook.

The API Worker owns that front door. It authenticates the webhook, validates the payload's shape and bounds, and normalizes every tracker family's dialect into one canonical telemetry shape, so that battery, power, signal, movement, and fuel mean the same thing no matter which device sent them. It groups the normalized readings into a batch and places that batch on a queue. The API Worker's job ends there: it stays at the edge, close to ingress and auth, and leaves interpretation to the Engine Worker.

The Engine Worker consumes the queue and does the thinking. It resolves each reading to a known device and vehicle, loads the vehicle's recent context, and runs it through the fleet state machine — the logic that decides whether the truck is moving, parked, or gone dark; that opens and closes trips; that detects stops and classifies them; that notices signal gaps; that watches the truck against its route; and that reads fuel and raises events. The Engine writes the results to the database and cache, publishes the events that deserve an alert, and runs the scheduled jobs that keep everything current between messages. Processing is serial per truck, so a vehicle's story is assembled in order, one reading at a time.

From there the picture flows outward. The database holds the durable record that the fleet app, admin portal, and customer tracking portal read from; the cache holds the live, fast-changing state — current position, active route, ETA, human-readable place labels. Alerts leave through WhatsApp and push, so a fuel drop or a route departure reaches a person while it still matters.

The four data planes ​

Everything Korido stores and computes belongs to one of four planes. They stack: the reference plane describes the world, the plan plane says what should happen, the observed plane records what did happen, and the intelligence plane learns from the accumulation.

The reference plane — the map ​

The reference plane is Korido's shared, curated model of the road itself: the named places a truck can be (waypoints), the curated geometry of each stretch of road between two of them (road_segments), the named paths that string those places into routes (corridors), and the reverse-geocoding label cache that turns a raw coordinate into a human place name (geocode_cache). This plane is maintained by Korido platform staff and shared across every tenant — the corridor from Douala to N'Djamena is the same road for everyone who drives it. Configure it once, and every fleet uses it.

The plan plane — what should happen ​

The plan plane is where a tenant declares intent. A mission is one planned journey for one vehicle: pick a route, assign a driver and truck, and it carries the load from origin to destination through an ordered set of waypoints. Mission templates capture a route and its presets so a common run becomes a one-tap dispatch; rule_sets hold the driving policy that applies to a mission — speed limits, night-driving windows, authorized fuel stations, prohibited stops; and convoys group missions that travel together. This plane is per tenant and editable: it is the office's stated plan for the work.

The observed plane — what actually happened ​

The observed plane is the immutable record of reality, written by the Engine as telemetry arrives. Raw readings land as positions; the state machine assembles them into trips (the driving windows), stops (parked intervals, each classified — customs, weighbridge, breakdown, fuel station, and more), data_gaps (windows where the truck went dark, classified by likely cause), waypoint_visits (arrivals at and departures from named places), and segment_traversals (one truck's observed crossing of one road segment — the spine of all later analytics). Alongside these sit vehicle_events and fuel_events — the noteworthy moments, from a fuel drain to a route departure — and corridor_deviations, the record of every excursion off the agreed route. These facts are never rewritten; they are the ground truth everything else is measured against.

The intelligence plane — what we learn ​

The intelligence plane sits above a single tenant and learns from the whole fleet's accumulated facts. Recurring slow patches cluster into slowdown_zones; recurring stop-and-event clusters become route_hotspots; disruptive incidents that block progress are captured as corridor_anomalies; and the segment_traversals accumulate into analytics that compare a truck with itself over time, a truck with its peers, and a driver with other drivers, surfacing correlations no single trip could reveal. This plane feeds back into the plan plane: what has been learned about a stretch of road sharpens the ETA and the Route Guard expectations for the next truck that drives it.

How it connects ​