Specification: Enable Scheduled Managed Charger Access¶

TLDR (Solution Summary)¶

• Build scheduled charger access control so depot operators can put chargers into freevend during open periods and managed access during restricted periods, with BetterFleet authorising own-fleet and agreement vehicles while recording unauthorised attempts as access denied.
• Charger access mode + add scheduled freevend and managed access states per charger + chargers follow depot operating patterns automatically.
• Access schedule + add recurring charger-level rules with timezone-aware effective times + operators can define when each charger requires authorisation.
• Authorised vehicle identifier set + classify identifiers as own-fleet, agreement, or unauthorised/unknown + managed-access attempts can be allowed or denied consistently.
• Access decision record + record each managed-access allow or deny outcome separately from faults and incidents + operations users can distinguish policy enforcement from charger failure.
• Denial signalling contract + define the supported charger or vehicle-facing denial response per protocol capability + drivers get the clearest available denial signal.

1. Summary¶

• Problem statement:
• Depot operators need chargers to be openly available at some times and restricted at others, but the current challenge does not define a product model for scheduled switching between freevend and managed access.
• During restricted periods, BetterFleet needs a reliable access decision model that allows known own-fleet and agreement vehicles, denies unknown vehicles, and records denials as policy outcomes rather than charger faults.
• Goal and success criteria:
• Define a scheduled managed charger access capability for BetterFleet Manage and charger integrations.
• Success is measured by:
  • operators being able to configure recurring charger-level managed-access periods;
  • chargers entering the expected access mode at scheduled times;
  • managed-access attempts producing correct allow or deny decisions for own-fleet, agreement, and unknown identifiers;
  • operations users seeing access-denied events separately from incidents and charger faults;
  • the product defining the denial signal available to drivers or charger users for each supported charger/protocol path.
• What will be built in this phase:
• Charger access mode + expose freevend and managed access as the effective access mode for each charger + users and systems can tell whether BetterFleet authorisation is required.
• Access schedule + allow recurring charger-level rules using account or depot-local time + chargers switch access mode without manual intervention.
• Managed-access authorisation + evaluate charger-provided vehicle identifiers against own-fleet and agreement vehicle identifier sets + allowed vehicles can start charging during restricted periods.
• Access-denied event + record denied attempts as access-control outcomes + operations users do not confuse denial with faults or incidents.
• Denial signalling contract + define the expected denial response for each supported charger/protocol capability + drivers receive the clearest available indication that charging was denied by access rules.
• Scope for this phase:
• In:
  • charger-level access mode modelling;
  • recurring charger-level schedules for freevend versus managed access;
  • authorisation against own-fleet and agreement vehicle identifiers;
  • access-decision recording for allowed and denied attempts;
  • operations visibility for access-denied outcomes;
  • conceptual denial signalling per supported charger/protocol capability.
• Out:
  • billing, tariff calculation, or settlement for agreement vehicles;
  • driver account management;
  • broad fleet-sharing marketplace behaviour;
  • depot-level, zone-level, or connector-level policy inheritance beyond what is needed for charger-level control;
  • agreement-vehicle import and agreement lifecycle management, except as a dependency that provides identifiers;
  • treating access denial as an incident by default.
• Current baseline (as of May 1, 2026):
• The Linear initiative states that chargers may be left in freevend when restricted access is needed.
• Vehicle access rules are not yet clearly modelled around own vehicles, agreement vehicles, and unknown vehicles for this capability.
• Access-denied attempts can be confused with charger failure because the product contract for policy denial is not defined.
• Future evolution guardrails:
• The model should allow later depot, zone, connector, and agreement-level policy layers without changing the meaning of charger-level rules.
• The identifier model should allow multiple identifier types per vehicle and per charger integration.
• Access decisions should remain auditable so later billing, settlement, reporting, or compliance work can consume them.
• The schedule model should support recurring operating patterns without blocking later exceptions, holidays, or temporary overrides.

2. Users and Use Cases¶

• Primary personas:
• Depot operator configuring which chargers are open and which are restricted.
• Operations user monitoring charging attempts and diagnosing failures or denials.
• Fleet or agreements administrator maintaining the vehicle identifiers that may charge during restricted periods.
• Driver or end user attempting to charge during a managed-access period.
• Support user investigating a failed or denied charging attempt.
• High-level user stories:
• As a depot operator, I want chargers to run in freevend during open-access periods so vehicles can charge without BetterFleet authorisation.
• As a depot operator, I want chargers to switch to managed access during restricted periods so only own-fleet and agreement vehicles can charge.
• As a depot operator, I want recurring schedules for charger access mode changes so normal operating patterns happen automatically.
• As an operations user, I want denied attempts recorded as access denied so I can distinguish policy enforcement from charger faults.
• As a support user, I want to see which identifier was denied and why so I can resolve misconfiguration or explain the outcome.
• As a driver, I need the charger or vehicle experience to make clear that charging was denied where the charger and protocol support that feedback.
• Edge cases and failure modes:
• A charger is offline or unreachable when its scheduled access mode should change.
• A charger integration cannot support remote freevend switching or pre-start authorisation.
• A charger sends an identifier type BetterFleet does not recognise.
• A vehicle has multiple identifiers, only one of which is known to BetterFleet.
• An agreement vehicle's identifier is stale or missing.
• A charging attempt starts near an access-mode boundary.
• Two recurring access rules overlap for the same charger.
• A scheduled managed-access period crosses midnight or a daylight-saving transition.
• A denied attempt is followed by a legitimate charger fault.

3. Conceptual Model Terms and Decisions¶

Key Terms¶

Decision Ledger¶

4. Domain Model and Eventstorming (Conceptual)¶

• Bounded context and ubiquitous language:
• Charger Access Control governs access mode schedules, effective mode evaluation, charger access-mode changes, and managed-access decisions.
• Vehicle Access Identity governs the mapping from charger-provided identifiers to own-fleet, agreement, and unknown access classes.
• Charging Operations Visibility governs how allowed and denied attempts appear to operators and support users.
• Aggregates and entities:
• Charger: charging asset with supported access capabilities and effective access mode.
• Access Schedule: recurring charger-level rule defining expected access mode over time.
• Vehicle Access Identity: active identifier and access class used for authorisation.
• Charging Access Attempt: a charger-reported attempt to start charging during managed access.
• Access Decision: allowed or denied result with reason and identifier context.
• Value objects:
• Access Mode: freevend or managed_access.
• Access Class: own_fleet, agreement, unknown, or unauthorised.
• Schedule Window: recurring local-time window with timezone-aware interpretation.
• Denial Reason: policy reason explaining why an attempt was denied.
• Domain events and triggers:
• AccessScheduleCreated when an operator creates a charger access schedule.
• AccessScheduleUpdated when an operator changes a recurring rule.
• EffectiveAccessModeEvaluated when the system determines which access mode applies now.
• ChargerAccessModeChangeRequested when the system asks a charger or integration to switch mode.
• ChargerAccessModeChanged when the charger reports or confirms the new mode.
• ManagedAccessAttemptReceived when a charger requests authorisation before charging starts.
• VehicleIdentifierClassified when BetterFleet maps the charger-provided identifier to an access class.
• AccessDecisionRecorded when BetterFleet records an allow or deny decision.
• AccessDeniedObserved when a denied attempt is surfaced to operations users.
• Commands, actors, and policies:
• ConfigureAccessSchedule by depot operator.
• EvaluateEffectiveAccessMode by schedule policy.
• ApplyAccessModeToCharger by charger integration policy.
• RequestManagedAccessAuthorisation by charger or integration.
• ClassifyVehicleIdentifier by vehicle identity policy.
• RecordAccessDecision by access-control policy.
• ShowAccessDeniedOutcome by operations visibility policy.
• Invariants and business rules enforced:
• A charger with effective mode freevend must not require a BetterFleet access decision before charging starts.
• A charger with effective mode managed_access must require a BetterFleet access decision before charging starts when the charger supports that path.
• Own-fleet and agreement identifiers must be allowed during managed access when active and valid.
• Unknown or unauthorised identifiers must be denied during managed access.
• A denied access attempt must be recorded as an access-denied event and must not be recorded as a charger fault or incident by default.
• Access schedule evaluation must use timezone-aware rules and store internal instants in UTC.
• Overlapping access schedules for the same charger must be prevented or resolved by an explicit priority rule.
• Access decisions must retain enough context for support users to explain the outcome without exposing sensitive identifiers unnecessarily.
• External systems and integrations:
• Charger integrations must expose whether freevend switching and pre-start authorisation are supported.
• Vehicle and agreement systems must provide or expose authorised identifiers.
• Operations views must consume access-decision records separately from charger fault and incident streams.

Interaction Flow¶

flowchart LR
  Operator["Depot operator"] --> Configure["Configure charger access schedule"]
  Configure --> Schedule["Access schedule saved"]
  Schedule --> Evaluate["Evaluate effective access mode"]
  Evaluate --> Apply["Request charger access mode change"]
  Apply --> Mode["Charger runs in freevend or managed access"]
  Mode --> Attempt["Charging attempt received"]
  Attempt --> Managed{"Managed access active?"}
  Managed -->|No| Freevend["Charging follows charger freevend behaviour"]
  Managed -->|Yes| Classify["Classify vehicle identifier"]
  Classify --> Decision{"Own-fleet or agreement?"}
  Decision -->|Yes| Allow["Record allowed decision and permit start"]
  Decision -->|No| Deny["Record access-denied event and deny start"]
  Deny --> Ops["Show access denied in operations views"]

Event Timeline¶

timeline
  title Scheduled Managed Charger Access
  AccessScheduleCreated: Operator defines recurring charger access mode periods
  EffectiveAccessModeEvaluated: System determines the current charger mode
  ChargerAccessModeChangeRequested: Integration is asked to switch mode
  ChargerAccessModeChanged: Charger confirms or reports effective mode
  ManagedAccessAttemptReceived: Charger asks for authorisation
  VehicleIdentifierClassified: Identifier maps to own-fleet, agreement, or unknown
  AccessDecisionRecorded: Allow or deny decision is stored
  AccessDeniedObserved: Operations user sees policy denial separately from faults

Event Dictionary¶

• AccessScheduleCreated: a recurring charger access rule was created | starts automated access-mode control | chargerId, accessMode, recurrence, timezone, createdAt | triggers future schedule evaluation.
• AccessScheduleUpdated: a recurring charger access rule was changed | keeps operating pattern current | scheduleId, changedFields, updatedAt | triggers re-evaluation.
• EffectiveAccessModeEvaluated: the current mode for a charger was derived | defines whether authorisation is required | chargerId, effectiveAt, accessMode, sourceScheduleId | may trigger mode change.
• ChargerAccessModeChangeRequested: the system requested freevend or managed access on the charger | applies the schedule to the physical charger | chargerId, requestedMode, requestedAt | awaits confirmation or error.
• ChargerAccessModeChanged: charger mode was confirmed or reported | confirms operational state | chargerId, accessMode, changedAt | updates visibility and audit.
• ManagedAccessAttemptReceived: a charger requested authorisation | starts policy decision | chargerId, identifierType, identifierHash, receivedAt | triggers classification.
• VehicleIdentifierClassified: an identifier was mapped to an access class | explains policy basis | identifierType, accessClass, matchedVehicleId | feeds access decision.
• AccessDecisionRecorded: an allow or deny decision was stored | creates audit and operations visibility | chargerId, accessClass, decision, reason, decidedAt | allows start or reports denial.
• AccessDeniedObserved: a denied attempt was surfaced to a user | separates policy denial from failure | decisionId, chargerId, observedAt | supports monitoring and support.

5. Requirements and Constraints¶

• Functional requirements:
• FR-001: The system shall represent each supported charger access mode as freevend or managed access.
• FR-002: Operators shall be able to configure recurring charger-level access schedules that set expected access mode over time.
• FR-003: Access schedules shall use depot or account-local presentation time while storing and evaluating effective instants with timezone-aware UTC semantics.
• FR-004: The system shall derive a charger's effective access mode from its applicable schedule at the time of evaluation.
• FR-005: The system shall request charger mode changes when a schedule boundary changes a charger's effective access mode and the charger integration supports remote mode switching.
• FR-006: The product shall expose charger capability status for remote freevend switching and managed-access authorisation before a charger can be treated as fully supported.
• FR-007: During managed access, the system shall evaluate charger-provided vehicle identifiers before allowing charging to start.
• FR-008: The system shall allow active own-fleet vehicle identifiers during managed-access periods.
• FR-009: The system shall allow active agreement vehicle identifiers during managed-access periods.
• FR-010: The system shall deny unknown or unauthorised identifiers during managed-access periods.
• FR-011: The system shall record each managed-access authorisation outcome as an access decision with enough context to support operational review.
• FR-012: The system shall record managed-access denials as access-denied events, separate from charger faults and incidents by default.
• FR-013: Operations users shall be able to see access-denied events for relevant chargers and distinguish them from faults.
• FR-014: Support users shall be able to identify the charger, time, identifier class, and denial reason for a denied attempt without exposing sensitive identifiers unnecessarily.
• FR-015: The product shall define the denial signal sent to the charger, vehicle, or driver for each supported charger/protocol path.
• FR-016: Overlapping access schedules for the same charger shall be prevented or resolved through an explicit priority rule visible to operators.
• FR-017: A failed charger mode change shall be visible as a charger access-control problem and shall not silently leave the charger assumed to be in the scheduled mode.
• Non-functional requirements:
• NFR-001: Schedule boundary handling shall be deterministic across midnight and daylight-saving transitions.
• NFR-002: Managed-access authorisation shall complete quickly enough for the charger integration's pre-start authorisation timeout.
• NFR-003: Access decision recording shall be auditable and resilient to repeated or retried charger authorisation requests.
• NFR-004: The first delivery should prefer additive API and UI changes to protect existing charger session and incident consumers.
• NFR-005: Rollout shall be controllable by feature flag or equivalent staged rollout mechanism where customer exposure needs phasing.
• NFR-006: Access-decision records shall avoid storing raw sensitive identifiers where a hashed or masked representation is enough for support.
• Constraints and assumptions:
• Chargers in scope can be switched between freevend and managed access remotely, or can be explicitly marked unsupported.
• Chargers in scope can request authorisation before charging starts during managed access.
• Agreement vehicle identifier management is provided by a separate process.
• Billing and settlement remain outside this phase.
• ADR 0009 requires timezone-aware datetime handling and UTC internal storage.
• ADR 0020 favours additive API evolution where possible.
• ADR 0023 supports domain-event modelling for domain-significant access decisions and downstream visibility.
• ADR 0011 and the local feature-flag workflow shape staged rollout.
• Build item coverage mapping:
• Charger access mode: FR-001, FR-004, FR-005, FR-006, FR-017, NFR-004, NFR-005
• Access schedule: FR-002, FR-003, FR-004, FR-016, NFR-001
• Authorised vehicle identifier set: FR-007, FR-008, FR-009, FR-010, FR-014, NFR-006
• Access decision record: FR-011, FR-012, FR-013, FR-014, NFR-002, NFR-003
• Denial signalling contract: FR-015, FR-017
• Verification notes:
• Requirements should later be validated with unit and integration tests around schedule evaluation, identifier classification, access decisions, and mode-change failure handling.
• End-to-end validation should cover at least one supported charger/protocol path for freevend switching and managed-access denial.
• Product validation should confirm that operations users can distinguish access denied from faults and incidents.

6. Interaction and Flow¶

Access Schedule Configuration¶

flowchart TD
  Start["Operator opens charger access settings"] --> Select["Select charger"]
  Select --> Capability{"Charger supports scheduled access?"}
  Capability -->|No| Unsupported["Show unsupported capability state"]
  Capability -->|Yes| Rule["Create recurring access schedule"]
  Rule --> Validate{"Schedule valid?"}
  Validate -->|No| Fix["Show overlap or timezone issue"]
  Validate -->|Yes| Save["Save access schedule"]
  Save --> Audit["Record schedule event"]
  Audit --> Evaluate["Evaluate next effective mode"]

Managed-Access Authorisation¶

sequenceDiagram
  participant Charger
  participant AccessControl as "Charger Access Control"
  participant Identity as "Vehicle Access Identity"
  participant Ops as "Operations Visibility"

  Charger->>AccessControl: Request authorisation(identifier)
  AccessControl->>Identity: Classify identifier
  Identity-->>AccessControl: Access class
  alt Own-fleet or agreement
    AccessControl-->>Charger: Allow charging
    AccessControl->>Ops: Record allowed access decision
  else Unknown or unauthorised
    AccessControl-->>Charger: Deny charging with supported signal
    AccessControl->>Ops: Record access-denied event
  end

Access Mode State¶

stateDiagram-v2
  [*] --> Freevend
  Freevend --> ManagedAccess: Scheduled restricted period starts
  ManagedAccess --> Freevend: Scheduled open-access period starts
  ManagedAccess --> ModeChangeProblem: Charger rejects or misses mode change
  Freevend --> ModeChangeProblem: Charger rejects or misses mode change
  ModeChangeProblem --> Freevend: Operator or integration restores freevend
  ModeChangeProblem --> ManagedAccess: Operator or integration restores managed access

7. Non-Technical Implementation Approach¶

• Phase 1: confirm supported charger/protocol paths.
• Identify which chargers can support remote freevend switching and managed-access authorisation.
• Define unsupported and partially supported capability states before exposing scheduling to operators.
• Phase 2: define the access policy model.
• Add the shared terms for charger access mode, access schedule, vehicle identifier, access class, and access decision.
• Confirm how own-fleet and agreement identifier sets are supplied to the authorisation process.
• Phase 3: deliver scheduled mode control.
• Add recurring charger-level schedules, effective-mode evaluation, and mode-change visibility.
• Include explicit handling for failed or delayed charger mode changes.
• Phase 4: deliver managed-access authorisation and denial recording.
• Evaluate charger-provided identifiers, allow known own-fleet and agreement vehicles, and deny unknown or unauthorised identifiers.
• Record each decision separately from charger faults and incidents.
• Phase 5: expose operations visibility and denial signalling.
• Show access denied as a policy outcome in operations views.
• Define charger or vehicle-facing denial behaviour by supported integration path.
• Design considerations:
• Keep the first scope charger-level and recurring-schedule based.
• Treat access denial as expected policy behaviour unless a separate fault occurs.
• Keep identifiers masked or hashed where raw values are not required.
• Prefer additive API and UI changes so existing charging session and incident behaviour remains stable.
• Dependencies and prerequisites:
• Supported charger/protocol capability list.
• Source of active own-fleet vehicle identifiers.
• Source of active agreement vehicle identifiers.
• Operations view decision about where access-denied events should appear.
• Rollout decision for customer exposure and feature-flag stage.

8. Open Questions¶

• Which charger models and protocols are in the first supported set for reliable freevend on/off control?
• Which charger models and protocols support pre-start managed-access authorisation within a safe timeout?
• Which identifier types are in scope first: MAC address, RFID, PIN, or another charger-provided identifier?
• Where is the authoritative source for own-fleet vehicle identifiers?
• Where is the authoritative source for agreement vehicle identifiers, and how often can it change?
• Should access-denied events appear only in operations views, or also in customer-facing reports?
• What is the exact denial signal for each supported charger/protocol path?
• How should the product handle a charging attempt that begins exactly at, or crosses, an access-mode boundary?
• Are temporary manual overrides needed in the first phase, or should they be deferred?
• What feature-flag stage and rollout language should be used for the first customer exposure?

9. Appendices¶

• Upstream challenge:
• Linear initiative: Enable Scheduled Managed Charger Access
• ADRs reviewed:
• ADR 0009 - Use Timezone Aware DateTimes and UTC
• ADR 0011 - Centralized feature flag repository
• ADR 0020 - API backwards compatibility and versioning
• ADR 0023 - Domain Event-Driven Architecture