Skip to content

Platform Architecture

Partner briefing — HDV charging-site booking & scheduling. Audience: CPMS engineering teams.

Our platform is two cooperating systems with a deliberate boundary between them:

System Role (EVRoaming terms) What it owns
Booking platform (booking-core) Booking Service Provider (BSP), operated for CPO tenants The schedule: bays × time-slots × power. Admission, optimization, site access credentials, booking guarantees.
CPMS platform (ev-suite) Technical CPO (charge-point management) Chargers: OCPP 1.6 / 2.0.1 connectivity, charger state, commands, smart charging, roaming (OCPI CPO + eMSP).

The boundary matters to you because the booking layer never speaks OCPP. It drives whichever CPMS manages a site's chargers through a pluggable CPMS adapter — our own CPMS is simply the first adapter target. A partner CPMS like yours plugs in the same way, over OCPI, without the booking layer knowing or caring what charger protocol you run behind it.

Role model

We use the EVRoaming Foundation HDV booking vocabulary throughout:

  • Transport Operator (TO) — the driver plus their fleet manager / dispatcher / TMS. The party that needs a charging slot.
  • EMP (e-Mobility Provider; OCPI spells it eMSP, some documents say MSP — same role) — the TO's mobility contract holder. Books on the TO's behalf over OCPI.
  • CPO (administrative) — our tenant: the operator who sells charging at the site. Every tenant has its own OCPI country_code + party_id.
  • CPO (technical) = the CPMS — the system that actually manages the charge points. One per connected CPMS; a single booking-platform installation talks to several CPMSs at once.
  • Site systems — the site owner's local infrastructure: gates, ANPR cameras, entry terminal, occupancy sensors, signage. We push data to them; they act autonomously (and offline).

The whole flow

flowchart LR subgraph TO["Transport Operator"] Driver["HDV driver"] Fleet["Fleet / TMS"] end EMP["EMP / eMSP\n(mobility provider)"] subgraph BSP["Booking platform (BSP)"] Sched["Scheduler\nbays × time-slots × power"] Intake["Booking intake\n+ pricing"] Cred["Offline credentials\nPIN / QR / plate"] Bill["Guarantee billing\nno-show & overstay fees"] Adapters["CPMS adapters"] end subgraph CPMS_OURS["Our CPMS (ev-suite)"] GWO["gateway-ocpp\n(WebSocket)"] MQ["EMQX (MQTT)"] MGR["ocpp-manager\nstate + durable commands"] DLM["Smart charging / DLM"] OCPIGW["OCPI CPO server\n+ eMSP backend"] end PCPMS["Partner CPMS\n(yours — OCPI 2.3)"] subgraph SITE["Site systems (site owner)"] Gate["Gate / ANPR /\nEntry terminal"] Ampel["Bay guidance\nGREEN · YELLOW · RED"] end CP1["Chargers (OCPP 1.6 / 2.0.1)"] CP2["Chargers (your fleet)"] Fleet -->|"book via EMP"| EMP EMP -->|"OCPI 2.3 bookings"| Intake EMP -.->|"OCPI locations / tariffs /\nsessions / CDRs"| OCPIGW Intake --> Sched Intake --> Cred Intake --> Bill Sched --> Adapters Cred -->|"reservation bundle\n(works offline)"| Gate Sched -->|"guidance state"| Ampel Adapters -->|"reserve / start / stop"| MGR Adapters -->|"OCPI commands\n(RESERVE_NOW, START_SESSION)"| PCPMS GWO <--> MQ <--> MGR CP1 <-->|"OCPP over WS"| GWO PCPMS <--> CP2 MGR --> DLM Driver --> Gate

Read it left to right: the TO books through their EMP over OCPI 2.3; the booking platform admits the request against the schedule, prices it, issues an offline site credential, and pushes a reservation bundle to the site. Near arrival, the booking platform reserves hardware through the CPMS adapter for that site — an internal command for our CPMS, standard OCPI commands for yours. Chargers only ever talk to their own CPMS.

The booking platform (BSP)

  • Schedule ownership. The unit of inventory is the bay (parking position + its charge point), scheduled over time-slots under a site-wide power envelope — so the schedule is feasible electrically, not just spatially. HDV-specific placement rules apply: vehicle dimensions, drive-through vs. side access, charging technology (CCS/MCS), dwell type (intermediate stop vs. overnight).
  • Scheduler. Every booking request passes admission through a real solver: a fast greedy placement with a constraint-programming (CP-SAT) sidecar for harder instances, behind a fallback so admission always answers. Disruptions (faults, late arrivals, slow charging) trigger debounced re-optimization; already-committed assignments are only moved when a charge point actually fails.
  • Booking is not a hardware reservation. At booking time we commit capacity, not a specific charger. The concrete charge point is fixed close to arrival and then reserved via the CPMS adapter — this keeps the schedule free to optimize and matches how HDV drivers actually use a site (the exact bay matters at arrival, not at booking).
  • Offline site credentials. On confirmation, each booking gets a self-issued PIN/QR credential and (optionally) a keyed number-plate match. Both are verified locally at the site, offline — an internet outage never strands a truck at the gate. Plates are never stored or transmitted in plaintext (keyed HMAC with rotation).
  • Guarantee billing only. The booking platform bills what makes the guarantee credible: reservation holds, no-show fees, overstay/blocking fees. Energy billing stays where it belongs — in the CPMS/EMP relationship. No overlap, no double billing.
  • Multi-tenant by organization. Every row, every API call, every OCPI surface is scoped to a tenant (a CPO). Each tenant publishes under its own OCPI party ID; peers only ever see their own bookings.

The CPMS platform (ev-suite)

  • OCPP connectivity. Chargers connect over WebSocket (OCPP 1.6 and 2.0.1) to a stateless gateway which bridges to an MQTT broker (EMQX); ocpp-manager owns charger state and a durable command queue — commands survive restarts and flaky charger connections.
  • Roaming. An OCPI CPO server (2.2, with 2.3 rolling out — see the onboarding guide) exposes locations, sessions, CDRs, tariffs, tokens and commands to EMP peers; an eMSP backend handles the app/driver side, including token authorization.
  • Smart charging / DLM. Dynamic load management allocates available site power across active sessions; the booking platform's power envelope and the CPMS's DLM operate on the same site reality from different ends (planning vs. real time).
  • Simulator. A full OCPP charger simulator backs integration tests and demos — end-to-end flows can run without physical hardware.

What this means for a partner CPMS

Your chargers, your OCPP, your charger state — untouched. The integration surface is OCPI:

  1. Your CPMS registers as an OCPI peer (versions + credentials handshake).
  2. We pull/receive your locations so the schedule knows your sites' bays and EVSEs.
  3. The booking platform sends standard OCPI RESERVE_NOW / START_SESSION / CANCEL_RESERVATION commands near arrival.
  4. Sessions and CDRs flow back over your normal OCPI CPO surface.

See OCPI23-ONBOARDING.md for the concrete endpoints and the first-30-minutes checklist, and USER_JOURNEYS.md for how the pieces behave end to end.

Maintainer footnote (internal — not part of the partner narrative): schedule ownership & bays/topology ADR-0009/0011/0024; power envelope ADR-0002; CP-SAT sidecar ADR-0012; late binding of the concrete CP ADR-0023; CPMS adapter pattern/surface ADR-0001/0010; offline credentials & plate HMAC ADR-0019/0020; guarantee-only billing ADR-0016/0021; multi-tenancy ADR-0003, per-tenant party IDs ADR-0032 context; ev-suite boundary: plan/17 D1, gateway/manager split ev-suite ADR-103/104/022; OCPI 2.3 typed module ev-suite ADR-141.