Waypoints and Road Geometry

What this chapter covers

The road network is the reusable map every mission is planned against: named places a truck can arrive at, and curated road geometry between them. This chapter describes waypoints (geofenced places), waypoint visits (the enter/exit/dwell record), and road segments (one curated geometry per road per route variant). Corridors assemble these into named paths in the next chapter; Route Guard turns a mission's roads into an acceptance region in Route Guard.

The picture

A waypoint is a point plus two radii. A road segment is a curated line between two waypoints, thickened into a polygon. A visit is what actually happened when a truck was inside a waypoint's geofence.

Waypoints — named geofenced places

A waypoint is a named place with a geographic centre and a circular geofence. Waypoints are the vocabulary of a route: an operator plans a mission by naming the places it passes through.

Every waypoint carries a type that says what kind of place it is:

• city, port, border, customs, weighbridge, toll_gate, fuel_station, warehouse, depot, checkpoint, rest_area, and custom.

Type carries operational weight, and the reason is worth setting up carefully, because it underpins everything Korido learns from a fleet. To compare how long two missions took on the same road, you need places both missions are guaranteed to pass through in the same way — otherwise you are comparing legs that started and ended at different points. Only some places give that guarantee.

The places that do are Tier-1 boundaries — stable points at which one mission can be measured against another. Only cities are universally mandatory: every truck on the same physical road passes through the same cities regardless of cargo, direction, or exemptions. Borders, customs posts, weighbridges, and fuel stations are visited conditionally — one truck stops, the next is waved through — so they are recorded as facts and dwell context rather than as comparison boundaries. A depot or warehouse becomes a Tier-1 boundary only when a specific mission names it as its own origin or destination.

This one distinction is what makes segment analytics comparable, and it carries all the way into segments and traversals.

Two radii

Each waypoint stores two radii, and they answer two different questions.

• radius_m is the operational radius — the geofence a truck is considered "at" the place within. It is generous on purpose: a port sprawls, and a truck manoeuvring in the yard should still read as present.
• core_radius_m is the tight core radius — a smaller ring, defaulting to a quarter of the operational radius, used to time the clean enter and exit moments that bound a segment. A wide operational radius would make transit timing noisy; the core radius gives a crisp boundary. Where the core radius is not set, the operational radius is used in its place.

Parent nesting — a port inside a city

Waypoints nest. A port sits inside the city that contains it through a parent link. Picture a fuel tanker loading at the Douala port, bound for N'Djamena — the truck this part will follow. The port geofence sits wholly inside the Douala city geofence:

This is what lets Korido handle a two-stage departure: the tanker leaving the port geofence has begun moving, but it has not yet left the city, so loading is only suspected until the outer city geofence is crossed. The nesting is what the mission engine reads to avoid declaring a departure the truck never made. That mechanism is described in the mission lifecycle.

Global or tenant-private

A waypoint can be global — shared by every fleet — or private to one tenant. The Douala port, the Touboro border, the Ngaoundéré weighbridge are the same physical places no matter which company's trucks pass through them, so they are curated once and shared. A tenant's own depot is private to that tenant. An operator can also drop an ad-hoc place on the map while building a mission (an "add a place" mode on the route map); that place is created as a tenant waypoint and spliced into the route in one step.

Geometry versioning

Whenever an operator edits a waypoint's position or radii, its geometry version is bumped. Historical records that referenced the old geometry keep their own frozen snapshot of the position and radius, so a place moved today does not silently rewrite what a traversal recorded last month. The version is the join key that lets analytics detect "this place's geometry changed since this row was written."

Waypoint visits — enter, exit, dwell

A waypoint visit is the record of one stay inside one waypoint's geofence. It opens the moment the truck crosses in and closes when it crosses out.

Each visit records:

• the entered_at and exited_at times and the resulting dwell duration;
• the exact entry and exit positions (which can sit up to a full radius away from the centre);
• how many stops happened inside the geofence and how far the truck moved within it;
• the approach direction — the compass bearing and eight-way sector on entry and exit, and a through-movement flag that is true when the truck drove through the place rather than reversing back out. Northbound and southbound trucks on the corridor sit on different historical-traffic distributions, so this direction data feeds later analysis.

Only one visit per truck-and-waypoint can be open at a time. When a truck crosses a waypoint boundary, one visit closes and, at the next place, another opens. Those closing and opening moments are the cuts that divide a mission into measurable segment traversals — the subject of Part 5's final chapter.

Road segments — one geometry per road

A road segment is the curated geometry of one road between two waypoints. It is the reference against which a truck's real path is judged: is it still on the road it was meant to take?

Each road segment stores:

• a from and a to waypoint;
• a centre line — the raw routed path between them, kept so the polygon can be regenerated at a different width without re-routing;
• a polygon — the centre line thickened by half the road's width, cached so the engine never has to buffer geometry on the hot path;
• a width (between 50 m and 5 km) that sets how far off the centre line still counts as "on the road";
• an ORS variant label (default, alt_1, alt_2) so two genuinely different roads between the same pair of waypoints — say a mountain route and a valley route — can both exist without colliding.

One direction, reused both ways

The central design rule is: one geometry per road, stored in one travel direction. The road from Douala to Yaoundé is the same asphalt whether a truck is driving north or south, so it is curated once. A mission travelling the other way simply reuses that geometry — the acceptance polygon is undirected, and each traversal carries its own direction, so one stored geometry serves both directions.

A reverse override exists only where the two directions genuinely differ — one-way streets, or split truck routes where loaded and empty trucks are sent along different roads. In the pilot corridor this is the exception: only a handful of the road pairs need a distinct reverse geometry; the rest are single geometries reused both ways. When a reverse override does exist, a reader serving the reverse direction prefers the explicit reverse row and otherwise falls back to the forward one.

Because a byte-identical mirror and a genuine divergence look the same to the database, the "one geometry per road" rule is upheld in the admin tooling, not by a constraint. The corridor editor curates roads, and "add reverse override" is a deliberate action an operator takes only when a road really splits.

Shared, not owned

Road segments are global, shared across every corridor that uses them, because one road belongs to many. The Douala–Yaoundé road is part of the N'Djamena trunk and the Bangui branch at once. Curating it once and letting every corridor reference it is what keeps the map consistent: fix the geometry in one place and every mission on every corridor that uses that road benefits.

Edge cases

• A truck idling in a yard past the end of the road. On arrival, a truck can be inside a waypoint's operational geofence but a few hundred metres past where the buffered road ends. That short stretch of city driving is inside the waypoint's geofence, so it does not read as leaving the road. Route Guard unions the waypoint geofences into the acceptance region precisely to absorb this; see Route Guard.
• Reverse travel with no override. With no reverse row, a southbound truck is judged against the northbound geometry. Because containment is direction-free and the polygon is symmetric about the centre line, this is exact — the reverse row would only ever differ if the physical road did.
• A waypoint moved after the fact. Editing a place's position or radius does not rewrite history: existing visits and traversals keep the snapshot of the geometry they were measured against, and the geometry version records that a change happened.
• Core radius unset. Older waypoints created before the tight core radius may not have one; the operational radius stands in until a backfill sets it, so segment timing degrades gracefully rather than breaking.

How it connects

• Corridors — how ordered waypoints resolve into a named path of roads.
• Route Guard — how a mission's roads and waypoint geofences become a frozen acceptance region.
• Segments and traversals — how waypoint-visit boundaries cut a journey into measurable pieces.
• Part 2 (telemetry) and Part 3 (the fleet engine) — where geofence entry and exit are actually detected from the position stream.