Specification: Visiting Vehicle Charging Visibility¶

TLDR (Solution Summary)¶

• Build cross-depot charging visibility so depot teams can tell when a vehicle is charging away from its home depot and when a visiting vehicle is charging on site.
• Depot vehicle list + add away-from-home visibility for home-depot vehicles charging elsewhere + Depot A can see charging status and the current charging depot.
• Depot vehicle list + add visiting-vehicle visibility for vehicles charging on site from another home depot + Depot B can see charging status and the vehicle's home depot.
• Troubleshooting timeline + add home-depot and charging-depot context to charging-session entries + operators can distinguish visiting sessions without manual lookup.
• Charging Sessions + define cross-depot attribution semantics for on-screen and exported output + finance and operations users can interpret session ownership and site usage consistently.
• Vehicle Charging Summary + define matching cross-depot attribution semantics + summary reporting stays aligned with Charging Sessions.
• Charging presence model + shape backend ownership, session location, and read-model responsibilities around BetterFleet DDD boundaries + future multi-site rules stop depending on ad hoc repository leakage.

1. Summary¶

• Problem statement:
  • Depot users currently lose context when a vehicle's home depot and charging depot differ.
  • The existing product behavior is split between home-depot vehicle ownership and charger-depot operational views, so users must infer the real state manually.
• Goal and success criteria:
  • Define one cross-depot charging visibility capability for depot vehicle views, the troubleshooting timeline, and the two relevant reporting surfaces.
  • Success is measured by:
  • a home-depot user being able to see that a home vehicle is charging away from home and where;
  • a hosting-depot user being able to see that a visiting vehicle belongs to another depot;
  • timeline and report outputs using the same depot-attribution meaning;
  • architecture review showing that the backend implementation aligns with BetterFleet's DDD standards.
• What will be built in this phase:
  • Depot vehicle list + show away-from-home charging state for home-depot vehicles + home-depot users keep operational awareness without switching depot context.
  • Depot vehicle list + show visiting vehicles with home-depot context + hosting-depot users can identify who is charging on site.
  • Troubleshooting timeline + enrich charging-session entries with cross-depot context + timeline sessions stop being anonymous beyond vehicle name.
  • Charging Sessions + define and present cross-depot attribution semantics + session-level reporting remains interpretable when a vehicle charges away from home.
  • Vehicle Charging Summary + define and present matching summary semantics + summary reporting stays consistent with the session-level contract.
  • Charging presence model + define DDD-aligned ownership, session-location, and projection responsibilities + implementation work has a stable conceptual contract.
• Scope (in/out) for this phase:
  • In:
  • active charging visibility for vehicles whose home depot differs from their charging depot;
  • depot-scoped vehicle surfaces;
  • troubleshooting timeline charging-session visibility;
  • report semantics for Charging Sessions and Vehicle Charging Summary;
  • DDD-aligned backend shaping expectations for the affected code.
  • Out:
  • exact database schema or API design;
  • final microcopy or final layout choice between separate tables, inline rows, or pills;
  • historical non-charging location history;
  • broad yard-state or multi-site overview redesign beyond the directly affected artifacts.
• Current baseline (as of March 23, 2026):
  • Vehicle ownership and depot vehicle retrieval are still keyed to home_depot.
  • Troubleshooting timeline data is still keyed to the selected depot's chargers and exposes vehicle identity without depot-attribution context.
  • Stakeholder discussion has already raised options such as extra tables or inline status treatment, but there is no canonical cross-depot contract yet.
  • Earlier report-parity work completed cost-attribution parity for the relevant reports, but did not define cross-depot charging visibility semantics.
• Future evolution guardrails:
  • This phase must keep it easy to extend cross-depot visibility to additional multi-site surfaces later.
  • This phase must not make one specific UI layout the only valid expression of the contract.
  • This phase must preserve home depot as ownership data rather than turning active charging location into a hidden ownership mutation.
• Not in scope:
  • technical design specifics such as database schemas, migration details, low-level endpoint contracts, or class-level design.

2. Users and Use Cases¶

• Primary personas:
  • Depot manager viewing vehicles for the vehicle's home depot.
  • Depot manager or operator viewing chargers and sessions for the hosting depot.
  • Finance or reporting user interpreting charging activity by depot.
  • Developer or reviewer validating that the backend implementation fits BetterFleet's DDD rules.
• High-level user stories:
  • As a home-depot user, I want to see when one of my vehicles is charging at another depot so I can understand its live state without losing ownership context.
  • As a hosting-depot user, I want to see that a charging vehicle is visiting from another depot so I can understand who the vehicle belongs to.
  • As a report user, I want cross-depot sessions to use explicit and consistent depot attribution so I do not misread charging activity.
  • As a developer or reviewer, I want the affected backend logic to be shaped around clear domain boundaries so future multi-site behavior is easier to extend safely.
• Edge cases and failure modes:
  • Vehicle has no home depot.
  • Charging-session data refers to an unknown or newly introduced vehicle whose ownership record is not yet fully available.
  • Vehicle is charging at its own home depot and should remain local.
  • Vehicle identity is known but depot-attribution context is incomplete.
  • Session has ended and should no longer appear as active visiting or away-from-home charging.
  • Report filters or groupings interact with cross-depot sessions.
  • The same vehicle appears in multiple operational surfaces and must not show conflicting depot meanings.

3. Conceptual Model Terms and Decisions¶

Key Terms¶

Decision Ledger¶

4. Domain Model and Eventstorming (Conceptual)¶

• Bounded context and ubiquitous language:
  • Vehicle Ownership governs the vehicle's home depot and stable ownership identity.
  • Charging Session Tracking governs active charging sessions and charger-location evidence.
  • Depot Operational Visibility governs home-depot and hosting-depot views of live charging state.
  • Reporting Attribution governs how cross-depot sessions are represented in Charging Sessions and Vehicle Charging Summary.
• Aggregates and entities:
  • Vehicle aggregate: vehicle identity, home depot, active status.
  • Charging Session aggregate: vehicle, charger, depot, start, end, live state.
  • Charging Presence View entity: derived relationship between vehicle ownership and charging location.
  • Report Attribution Record entity: report-safe representation of depot meaning for a session or summary row.
• Value objects:
  • Depot Attribution: home depot, charging depot, relationship type.
  • Presence Classification: local, away_from_home, visiting, unassigned_home_depot.
• Domain events and triggers:
  • ChargingSessionStarted when a vehicle begins charging on a charger tied to a depot.
  • ChargingPresenceDerived when the system classifies the relationship between home depot and charging depot.
  • HomeDepotVisibilityUpdated when the home-depot view gains or loses away-from-home state.
  • HostingDepotVisibilityUpdated when the hosting-depot view gains or loses visiting state.
  • ReportAttributionEvaluated when report output applies the cross-depot semantics.
  • ChargingSessionEnded when active visiting or away-from-home visibility should be cleared.
• Commands, actors, and policies:
  • RecordChargingSession by the system from session or location evidence.
  • DeriveChargingPresence by policy when a session starts, changes, or ends.
  • ViewHomeDepotVehicles by depot user.
  • ViewHostingDepotVehicles by depot user.
  • GenerateChargingSessionsReport by report user.
  • GenerateVehicleChargingSummaryReport by report user.
• Invariants and business rules:
  • Home depot ownership does not change because a vehicle charged elsewhere.
  • One active charging session produces one deterministic charging-presence classification.
  • The same session must not show conflicting depot meanings across depot views, timeline, and reports.
  • Vehicles without a home depot must remain visible with an explicit unassigned state instead of being silently dropped.
  • Sessions with unresolved or newly introduced vehicle identity must remain visible with an explicit unknown state instead of being silently dropped.
• External systems and integrations:
  • Charging-session and charger-location evidence flows in from the existing transaction and charger data sources.
  • Depot vehicle views, troubleshooting timeline, and reporting surfaces all consume the resulting attribution meaning.
  • Error handling must prefer explicit degraded states over silent omission when home-depot or charging-depot context is incomplete.

Interaction Flow¶

flowchart LR
  Session["ChargingSessionStarted"] --> Derive["Derive Charging Presence"]
  Derive --> Match{"Home Depot == Charging Depot?"}
  Match -->|Yes| Local["Project Local Charging State"]
  Match -->|No| Away["Project Away-From-Home State"]
  Away --> HomeView["Update Home-Depot View"]
  Away --> HostView["Update Hosting-Depot View"]
  Away --> Reports["Apply Report Attribution Semantics"]
  Local --> Reports

Event Timeline¶

timeline
  title Visiting Vehicle Charging Visibility
  ChargingSessionStarted: Vehicle starts charging at a depot
  ChargingPresenceDerived: Home and charging depots are compared
  HomeDepotVisibilityUpdated: Away-from-home state becomes visible to the owning depot
  HostingDepotVisibilityUpdated: Visiting state becomes visible to the hosting depot
  ReportAttributionEvaluated: Reports apply the same depot meaning
  ChargingSessionEnded: Visiting or away-from-home visibility is cleared

Event Dictionary¶

• ChargingSessionStarted: a vehicle begins charging at a depot | starts live visibility logic | vehicleId, chargingDepotId, chargerId, startedAt | triggers presence derivation.
• ChargingPresenceDerived: the system classifies local, away-from-home, visiting, or unassigned | gives every surface one depot meaning | vehicleId, homeDepotId, chargingDepotId, classification | triggers projections.
• HomeDepotVisibilityUpdated: the home-depot surface changes for an active vehicle | keeps ownership-side visibility current | vehicleId, homeDepotId, classification | updates depot vehicle view.
• HostingDepotVisibilityUpdated: the hosting-depot surface changes for an active vehicle | keeps site-side visibility current | vehicleId, chargingDepotId, classification | updates depot vehicle view and timeline.
• ReportAttributionEvaluated: report output applies the cross-depot meaning | keeps report contracts aligned | reportName, vehicleId, homeDepotId, chargingDepotId, classification | drives reporting behavior.
• ChargingSessionEnded: the active charging relationship ends | clears active visibility | vehicleId, chargingDepotId, endedAt | removes visiting or away-from-home state.

5. Requirements and Constraints¶

• Functional requirements:
  • FR-001: The system shall derive a canonical Charging Presence classification from Home Depot, Charging Depot, and active charging state for each active charging session.
  • FR-002: The home-depot vehicle surface shall show away-from-home vehicles and identify the charging depot for each active away-from-home charging session.
  • FR-003: The hosting-depot vehicle surface shall show visiting vehicles and identify the home depot for each active visiting charging session.
  • FR-004: The troubleshooting timeline shall expose home-depot and charging-depot relationship context for cross-depot charging sessions.
  • FR-005: Charging Sessions shall define and present explicit cross-depot attribution semantics consistently in both on-screen and exported output.
  • FR-006: Vehicle Charging Summary shall define and present explicit cross-depot attribution semantics consistently with Charging Sessions.
  • FR-007: Same-depot charging sessions shall preserve their existing local interpretation and shall not be reclassified as visiting or away-from-home.
  • FR-008: Vehicles without a home depot, and sessions whose vehicle identity cannot yet be matched to a complete ownership record, shall remain visible with explicit unassigned or unknown state rather than being omitted from the new contract.
  • FR-009: The implementation shall preserve Home Depot as stable ownership data and shall derive Charging Depot from charging-session or charger-location evidence instead of overwriting ownership data.
  • FR-010: Backend changes for this capability shall separate ownership rules, charging-session logic, and read-model or query responsibilities so the behavior maps cleanly to BetterFleet DDD boundaries.
• Non-functional requirements:
  • NFR-001: The same active charging session shall produce the same depot-attribution meaning across depot vehicle surfaces, troubleshooting timeline, and reporting surfaces.
  • NFR-002: Cross-depot visibility shall be additive to current same-depot behavior and shall not require users to reconcile conflicting meanings across multiple product surfaces.
  • NFR-003: Architecture review shall confirm alignment with BetterFleet's canonical DDD guidance in bf-manage-core/docs/DDD/agent.md, including clear domain, service, ports, adapters, and test responsibilities.
  • NFR-004: The chosen read path shall remain suitable for depot-scoped vehicle and timeline rendering without pushing cross-depot reconciliation into manual UI stitching.
• Constraints and assumptions:
  • Existing home_depot data remains the ownership source of truth for this phase.
  • Charging depot is derived from charger and charging-session location evidence.
  • This specification defines behavior and architecture guardrails, not the final layout choice.
  • No canonical challenge artifact exists yet; this specification starts with challenge_ref: TBD.
  • FLE-49 is a placeholder-shaped issue and must be decomposed into unit user stories before governed delivery starts.
• Build item coverage mapping:
  • Away-from-home depot vehicle visibility build item -> FR-001, FR-002, FR-007, FR-009, NFR-001
  • Visiting-vehicle depot visibility build item -> FR-001, FR-003, FR-007, FR-009, NFR-001
  • Troubleshooting timeline build item -> FR-004, NFR-001, NFR-004
  • Charging Sessions report build item -> FR-005, NFR-001, NFR-002
  • Vehicle Charging Summary report build item -> FR-006, NFR-001, NFR-002
  • DDD-aligned charging presence model build item -> FR-008, FR-009, FR-010, NFR-003, NFR-004
• Verification notes:
  • FR-001 through FR-004: validate through story-level scenario coverage across home-depot and hosting-depot views.
  • FR-005 and FR-006: validate through report contract review and output comparison.
  • FR-010 and NFR-003: validate through architecture review against the BetterFleet DDD guide before implementation closes.

6. Interaction and Flow¶

• User journey or process steps:
  • A vehicle starts charging at a depot.
  • The system derives whether the session is local, away-from-home, visiting, or missing home-depot ownership.
  • The home-depot surface reflects away-from-home charging when relevant.
  • The hosting-depot surface and timeline reflect visiting charging when relevant.
  • Reports apply the same cross-depot meaning when presenting session or summary data.

Flowchart Cross-Depot Visibility¶

flowchart TD
  A["Vehicle starts charging"] --> B["Derive charging presence"]
  B --> C{"Home depot known?"}
  C -->|No| D["Classify as unassigned_home_depot"]
  C -->|Yes| E{"Home depot equals charging depot?"}
  E -->|Yes| F["Classify as local"]
  E -->|No| G["Classify as away_from_home and visiting"]
  D --> H["Project visibility and report semantics"]
  F --> H
  G --> H

Sequence Diagram Cross-Depot View¶

sequenceDiagram
  participant Session as Charging Session Source
  participant Presence as Charging Presence Policy
  participant Home as Home-Depot View
  participant Host as Hosting-Depot View
  participant Reports as Reporting Surface
  Session->>Presence: ChargingSessionStarted(vehicle, charging depot)
  Presence->>Presence: Compare home depot and charging depot
  Presence-->>Home: Update away-from-home visibility when depots differ
  Presence-->>Host: Update visiting visibility when depots differ
  Presence-->>Reports: Apply same depot-attribution semantics

7. Non-Technical Implementation Approach¶

• Approach overview:
  • First lock the canonical charging-presence contract and the DDD alignment rules.
  • Deliver through narrow stories across depot vehicle surfaces, timeline visibility, and reporting follow-through.
  • Keep the implementation boundary on the canonical artifacts and their mirrored project/story structure rather than one umbrella issue.
• Design considerations:
  • Favor one shared business meaning across surfaces over quick per-surface UI fixes.
  • Preserve layout flexibility so stories can choose between separate sections, inline indicators, or pills without changing the contract.
  • Treat DDD alignment as part of the delivery definition, not a later refactor.
• Dependencies and prerequisites:
  • Agreement on the cross-depot reporting meaning for Charging Sessions and Vehicle Charging Summary.
  • Access to the relevant depot vehicle and timeline surfaces during story shaping and validation.
  • Architecture review against BetterFleet's DDD guidance before the story set is considered complete.

8. Open Questions¶

• Should the report presentation use dedicated Home Depot and Charging Depot fields, or a more compact derived status when depots differ?
• Should the first depot vehicle delivery use separate sections or tables for away-from-home and visiting vehicles, or inline indicators within the existing grid?

9. Appendices¶

• Inputs reviewed:
  • Problem statement and stakeholder comments discussing separate tables, pills, timeline behavior, and report questions
  • Earlier report-parity capability work for the relevant reports
  • BetterFleet workflow docs for governed work and Linear mirroring
  • BetterFleet DDD guidance in bf-manage-core/docs/DDD/agent.md