Worked Example¶

This example carries one charging outcome through the whole model. Use it when the ontology feels abstract.

Scenario¶

A depot imports tomorrow morning's work. Vehicle BUS-142 must leave at 06:20 with enough charge to complete its first block plus reserve. Overnight, the site receives a lower-capacity grid signal. Smart charging must still make the vehicle ready, keep the site within limits, and preserve evidence for support, reporting, and any commercial allocation.

End-To-End Flow¶

flowchart LR
  Schedule["Schedule import<br/>route, block, duty, departure"]
  Work["work<br/>first morning block"]
  Vehicle["vehicle<br/>BUS-142 state and capability"]
  Requirement["energy requirement<br/>target SoC, kWh, deadline, reserve"]
  Envelope["operating envelope<br/>lower site capacity window"]
  EnergySystem["energy system<br/>microgrid, chargers, meters, limits"]
  Allocation["charging allocation<br/>who charges, where, when, power"]
  Command["charger command<br/>profile or limit"]
  Session["charging session<br/>meter and status evidence"]
  Readiness["readiness outcome<br/>met, missed, or at risk"]
  Incident["incident / support state<br/>fault, stale data, missed charge"]
  Commercial["commercial record<br/>tariff, cost allocation, CDR if needed"]
  Report["reporting projection<br/>cost, carbon, reliability, proof"]

  Schedule --> Work
  Work --> Requirement
  Vehicle --> Requirement
  Requirement --> Allocation
  Envelope --> EnergySystem
  EnergySystem --> Allocation
  Allocation --> Command
  Command --> Session
  Session --> Readiness
  Session --> Commercial
  Session --> Report
  Readiness --> Report
  EnergySystem --> Report
  Session --> Incident
  Incident --> Report

Event Timeline¶

sequenceDiagram
  participant Plan as Schedule / planning source
  participant Core as BetterFleet domain layer
  participant Grid as Grid or flexibility source
  participant SC as Smart charging
  participant CSMS as CSMS / Connect boundary
  participant Charger as Charging station
  participant Reports as Reports / support views
  participant Commercial as Commercial allocation

  Plan->>Core: work schedule imported
  Core->>Core: energy requirement calculated
  Grid->>Core: capacity constraint received
  Core->>Core: operating envelope applied to energy system
  SC->>Core: request feasible charging allocation
  Core->>SC: allocation with lineage to work and envelope
  SC->>CSMS: set charging profile or limit
  CSMS->>Charger: OCPP command
  Charger->>CSMS: status and meter evidence
  CSMS->>Core: session and charger-state events
  Core->>Reports: readiness, cost, carbon, and reliability projections
  Core->>Commercial: tariff or CDR input if the session needs billing/settlement

Coordinate Classification¶

Moment	Problem coordinate	Physical coordinate	Core concept	Main standards or feeds
Schedule arrives	Operations & Dispatch -> Depot & Integration	route, block, duty, vehicle, depot, time	`work`	VDV 452, VDV 462/NeTEx, GTFS, TransXChange
Readiness target is calculated	Operations & Dispatch -> Dispatch & Scheduling	vehicle, battery, block, departure, reserve	`energy requirement`	VDV 463 if an upstream system sends charging requests
Grid capacity changes	Energy & Cost Management -> Advanced Energy & Grid	grid connection, microgrid node, time window	`energy system`	OSCP, OpenADR, DERMS feeds
Allocation is planned	Smart Charging -> Load Management	vehicle, charger, connector, site capacity, time	`charging`	OCPP charging profiles, site telemetry
Charger executes	Smart Charging -> Charger Control	charging station, EVSE, connector, meter, vehicle	`charging`, `vehicle activity`	OCPP, ISO 15118 where available
A charger fault appears	Incidents & Notifications -> Detection	charger, EVSE, connector, comms path, time	failure projection	OCPP status, diagnostics, telemetry freshness
Readiness is shown	Reporting & Insights -> Operational Dashboards	depot, vehicle, charging session, work deadline	read model	projections from work, session, telemetry, incident state
Cost or settlement is produced	Roaming & Shared Charging -> Commercial Settlement & Shared Charging	session, tariff, meter, invoice, party, time	commercial record	OCPI, OICP, OCMF, payment systems

Implementation Touchpoints¶

Surface	Role in this example	Main thing to protect
`bf-schedule-creator`	Converts source schedule formats into operations-ready work context.	Work identity and time validity.
Plan	Tests whether future work can be done with candidate fleet, charger, and grid capacity.	Scenario assumptions and planning horizon.
Manage domain services	Own live operational state, readiness, charging meaning, and reporting projections.	Domain boundaries and lineage.
Microgrid / energy model	Owns topology, limits, envelopes, and supply-side quality state.	Protocol-neutral constraint state.
Smart charging	Turns requirements and constraints into charger allocations.	Feasible, auditable control decisions.
Connect / CSMS boundary	Translates domain decisions to charger protocol messages and charger evidence back to the domain.	Adapter isolation and raw evidence retention.
Roaming / commercial services	Attach access, tariff, CDR, payment, or allocation meaning where needed.	Separation between physical energy transfer and commercial settlement.
Reports and support	Explain outcome, failure, cost, carbon, and readiness with traceable evidence.	Rebuildable projections and support-grade reasoning.

What This Example Teaches¶

One physical charging session can support operations, energy, incidents, reporting, and commercial views.
The domain owner changes with the decision being made.
Standards are input and output boundaries; BetterFleet concepts sit in the middle.
Reports and support views need lineage back to work, envelope, allocation, command, meter, and session evidence.