Handbook

Appearance

The Admin Portal ​

What this chapter covers ​

The admin portal at admin.korido.net is the operating console for the Korido platform team. This chapter describes who works in it, the platform tasks it owns — tenant and hardware administration, curation of the shared road network, cross-fleet analytics, and operational tooling — and why its cross-tenant reach is deliberate.

Who it is for ​

The admin portal is for Korido staff holding the platform-only admin role. A tenant owner never becomes an admin, and an admin never becomes a tenant owner except through an explicit, audited impersonation handoff. That separation is the whole point: the portal answers platform questions a single company's dashboard cannot.

  • Which tenants exist, and are they configured correctly?
  • Which tenant has a telemetry, WhatsApp, fuel, queue, or freshness problem?
  • Are the shared corridors and waypoints healthy?
  • Where along the corridor is GSM coverage failing, across every fleet?
  • Which fleets are producing alert volume that needs a support call?

The portal is a separate deployment from the fleet app with its own session and cookies. It is a daytime back-office tool: it ships a single light theme by design, with no dark mode.

Tenants, hardware, and money ​

The tenants list is the primary support index — tenant identity plus operational hints (vehicle and trailer counts, onboarding completeness, recent activity), built for a quick support scan. A tenant's detail page gathers its users, vehicles, trailers, documents, WhatsApp stats, and fuel configuration, and it is the launch point for owner impersonation. An onboarding wizard walks a new company from owner and truck through to an optional trailer and tracker in a few guided steps.

Beyond the tenant walls, two platform-wide surfaces manage the physical fleet. An inventory surface tracks every device, SIM, component, supplier, and batch across all tenants plus Korido's unassigned stock, with the full provisioning lifecycle — create, assign, install, swap, uninstall, decommission. Editing a device also carries a per-device expected-silence override — the longest a specific tracker may stay quiet before it counts as offline, entered in minutes (from 1 minute to 24 hours); left blank, the device falls back to its model's reporting cadence. It sits at the top of the silence chain the offline alert and the tracking portal both read, so a sleepy unit is told apart from a genuine outage without touching tenant-wide settings. A payments ledger records the platform revenue side with record, void, and CSV export.

Impersonation is the support bridge into a tenant's own experience. An admin picks an eligible owner, the platform mints a short-lived handoff token, and the fleet app redeems it into a clearly-marked, reversible impersonated session. The portal does not mirror every owner feature just to support one — it hands the operator the real owner surface instead.

Curating the road network ​

The shared road network is platform intelligence: owners select corridor coverage for their missions, but only admins define it. This keeps Route Guard behavior consistent across every fleet and prevents one tenant from changing route logic that others depend on. The corridor workbench is a map-first editor organized into three layers that build on one another.

  • Waypoints are the named anchors along the corridor — ports, depots, border crossings, checkpoints, and known places. Editing a waypoint's geometry bumps a geometry version and is preflighted for downstream impact, because other structures reference it.
  • Road segments are the global travel corridors between a pair of waypoints. An admin previews candidate driving routes, then saves a segment as a centerline plus a width, which Korido buffers into the polygon Route Guard watches. Editing a segment's centerline or width recomputes that polygon — and recomputes the Route Guard polygon of any in-flight mission that references it, closing the affected active deviations with a replacement reason. A pure name or active-state change does not trigger that propagation.
  • Named corridors are ordered waypoint routes — Douala → N'Djamena and its siblings — assembled origin → interim → destination. This is the per-road curation view. For every consecutive leg, the admin can pin a variant: choose exactly which road segment carries that leg, with "automatic (canonical)" as the default. And where a leg has only a forward segment, an explicit reverse override action creates its opposite-direction variant, so a corridor driven the other way is guarded just as tightly. Naming a corridor once is what lets the fleet app's quick-assign infer coverage from an origin and destination.

The model is deliberately additive. Segment deletion is a reversible archive — the segment is marked deleted and can be restored — and deliberately does not propagate: a geometry edit re-unions live missions and closes affected deviations, while a deletion simply retires the row. The full corridor and Route Guard model is the subject of Part 4 — The road network.

Cross-fleet analytics and benchmarks ​

Because the admin portal sees every tenant, it is the natural home for benchmarks no single fleet could compute. Segment analytics pools every tenant's traversals of a curated segment into one performance picture: median and 90th- percentile transit times, day-versus-night breakdowns, and the slowest segments across a 7-, 30-, or 90-day window. Every curated segment appears even when it has no samples yet. These are deliberate platform-wide comparisons with no single tenant's identity attached — a shared map of how the corridor really performs. The intelligence behind them lives in Part 6 — Fleet intelligence.

Operational tooling ​

Three surfaces keep the platform observable and the corridor legible:

  • GSM coverage maps connectivity along the corridor across every vehicle and provider, revealing repeated dead zones, provider-specific black spots, and vehicle-specific antenna trouble. It is diagnostic context, not an automatic verdict — a coverage gap explains a silent stretch; it does not excuse every offline event.
  • Alert volume gives cross-tenant operational context: which fleets are producing unusual event volume and which event types dominate, so support knows where to reach out. This is distinct from the fleet app's per-tenant alert triage.
  • Health reads the backend's deep-health check and maps it into clear operational states for the database, telemetry freshness, storage, dead-letter depth, and queue backlog — the first stop for "is Korido healthy right now?"

The boundaries of this surface ​

  • Cross-tenant, on purpose. The portal deliberately reads across tenant walls where a platform task requires it. That reach is confined to the admin role and the platform surfaces; it never leaks into the tenant-scoped fleet app.
  • Owner access happens through impersonation. Platform staff who need the owner experience impersonate an owner rather than rebuilding fleet workflows here.
  • Global edits announce their blast radius. Corridor and waypoint changes can affect active missions, so the workbench distinguishes name-only edits from geometry edits that propagate.
  • Support context only. WhatsApp stats and alert volume are triage context; they are not a messaging console with template editing, resend, or subscription management.

How it connects ​