User Journeys¶

How the platform behaves end to end, from booking to departure. Anything not yet live is marked planned — everything else is running today.

Roles used below: TO = Transport Operator (driver + fleet/TMS), EMP = the TO's mobility provider (OCPI eMSP), BSP = the booking platform, CPMS = the charge-point management system for the site (ours or a partner's).

a) Fleet books an HDV charging slot via their EMP¶

The fleet plans a stop; their EMP books it over OCPI 2.3.

• The EMP sends location, time window, an OCPI token for the driver, and optionally an exact EVSE, vehicle type and dimensions. An exact EVSE is not required — the scheduler places the truck; the concrete bay is fixed near arrival.
• Admission is a real solve, not a calendar lookup: bay compatibility (height/length/weight, left/right/drive-through access, CCS vs. MCS) and the site's power envelope are checked before we say yes. No feasible slot → REJECTED, immediately, honestly.
• The confirmation carries the offline entry credential (PIN/QR) — served exactly once, in the creation response.
• Price in the confirmation: planned. Reservation and penalty fees are configured per tenant today and applied at billing time; echoing total_cost on the OCPI booking response and publishing the fee schedule as OCPI Tariffs is designed and scheduled — being rolled out, not yet live at time of writing. Verify current state at demo.

b) Truck arrives — offline entry, bay guidance, charging starts¶

• The site adjudicates access, not us. The gate verifies the credential or the plate match against the reservation bundle we pushed earlier — fully offline. Plates are matched via keyed HMAC against active reservations only; no plaintext plate ever crosses the wire.
• Bay guidance (traffic-light model): every charge point carries a computed state — GREEN free, YELLOW reserved soon (with a masked plate hint so the right driver recognises their bay), RED occupied or faulted. The site's lights/signage render it; EMPs and navigation feeds get availability derived from the same state.
• Hardware is reserved lazily, near arrival — so an early re-plan never has to unwind a charger reservation made days ahead.
• Misuse is detected: a truck occupying a bay without a booking is flagged as illegal parking; a session starting on a different charger than the attended bay's is flagged as misuse (enforcement is the site's action, on our signal).

c) Departure — and the schedule holds¶

• Every booking has an estimated time of departure (ETD). During charging we track progress (SoC/energy delivered where available) and refresh the ETD; the driver sees it on bay signage data we push.
• If a vehicle charges slower than planned, the scheduler throttles-and-extends within the power envelope and re-optimizes downstream bookings — the schedule bends before it breaks. Energy estimation never hard-fails: with full SoC/battery data it is precise, with none it falls back to conservative vehicle-class tiers.
• Overstay: occupancy beyond the booked window is detected (occupancy sensors + session state) and protects downstream bookings via re-optimization. Overstay/blocking fees exist as per-tenant configured terms applied by the billing engine; publishing them machine-readably as part of the OCPI tariff/terms surface (so the fee is provably communicated before booking) is planned — being rolled out alongside the price echo in journey (a). Inside the booked window there are no idle fees — a booked slot is the driver's time.

d) No-show — slot release + fee¶

• The grace period is per-site configuration. The timer is durable — a process restart never loses a pending no-show check.
• The released capacity immediately re-enters the schedule for other bookings and ad-hoc arrivals.
• The no-show fee is charged idempotently by the guarantee engine (every billing action is event-keyed — retries never double-charge).
• Planned: a timely ETA update from the TO/TMS ("stuck in traffic, 40 min late") deferring the no-show release and triggering a re-slot offer. Today the EMP's move is cancel + rebook, which is fast and free of charge inside the cancellation window.

e) Ad-hoc (non-booked) driver charging via roaming¶

Booked trucks and walk-in roaming customers share the same sites.

• The driver authorizes via their EMP as at any roaming site: token authorization on the CPMS's OCPI CPO surface (tokens/.../authorize), or a START_SESSION command from the EMP; the CPMS runs the session and delivers session objects and CDRs back over OCPI. The booking layer is not in that loop — ad-hoc charging is standard OCPI roaming.
• The booking layer's job is to keep the two populations from colliding: guidance steers ad-hoc drivers to GREEN bays, reserved bays show YELLOW/RED, and an ad-hoc vehicle parked on a reserved bay is flagged (illegal parking) so the site can react before the booked truck arrives.
• Planned: power-allocation priority for booked sessions over ad-hoc ones when the site is power-constrained (today priority applies to placement; extending it into the live power-sharing path is designed but not built).

f) Site / CPO operator view¶

• Schedule board: the operator dashboard shows bays × time, live booking states (the same eight states the API exposes), occupancy, and guidance state per bay.
• Disruptions: a charge-point fault triggers reassignment of affected bookings — but only actual failures move already-committed assignments; the optimizer never shuffles trucks for marginal gains once a concrete bay is promised. Re-optimization is debounced and durable: bursts of disruption events collapse into one re-solve.
• Operations: system health (adapter connectivity, sync freshness, queue depth) is computed and exposed; the ops view surfaces illegal parking, misuse flags, and no-show outcomes.
• Planned: a maintenance calendar (block bays for future windows and auto-inform affected bookings) and an explicit ops alarm when a committed booking becomes unservable.

Booking states (the full set)¶

REQUESTED → CONFIRMED → ATTENDING → COMPLETED, with CANCELLED, EXPIRED, NO_SHOW, REJECTED as terminal branches. Always uppercase, everywhere — API, OCPI, dashboard. Details in OCPI23-ONBOARDING.md.

Maintainer footnote (internal — not part of the partner narrative): (a) intake/admission ADR-0011/0024/0025, credential-once ADR-0020, price echo & tariff publication ADR-0032 (proposed); (b) site adjudication ADR-0018/0019, plate HMAC ADR-0020, Ampel ADR-0022, lazy hardware reserve ADR-0023 context; (c) ETD ADR-0014, throttle-and-extend ADR-0025, overstay terms ADR-0021 + ADR-0032 increment 5 / G11; (d) durable timers ADR-0008, guarantee engine ADR-0016/0021, ETA deferral G1/G10 (planned); (e) roaming via ev-suite gateway-ocpi, booked-power priority S1/D7 (planned); (f) failure-only reassignment ADR-0023, reopt module, maintenance calendar 4.3.1/D10 (planned); statuses ADR-0007.