Google Sign-In Required

Use your company Google account to access the BetterFleet private content.

Back to private home

BetterFleet Support Private
Skip to content
BetterFleet Dev Wiki
Implementation Specification: BBA Microgrid Controller
Initializing search
    bf-dev
    • Home
    • Product Capabilities
    • Process
    • Current Work
    • System Design
    • Software Reference
    • Operations
    bf-dev
    • Home
      • Overview
      • Manage
      • Overview
      • Product Engineering Workflow
      • Product Engineering Delivery
      • Product Engineering Workflow in Linear
        • GitLab Feature Flags
        • In-App Docs Authoring
        • Release Notes
      • Templates
      • Publishing
      • Workflow Companions
      • Overview
      • Active Artifacts
      • Backlog Artifacts
      • Archived Artifacts
      • Overview
      • Microgrid
      • OSCP
        • Challenge
        • Specification
        • Spec
        • Architecture
        • Overview
        • Script Runtime Model
        • Compose Profiles and Modes
        • Repo Topology
        • CI and Release Integration
        • Overview
        • Internal Application Diagrams
          • Overview
          • Web Model
          • Core Model
        • Service Interaction Flows
        • Data and State
          • Index
          • bf-manage-web
          • bf-manage-core
          • bf-manage-connect
          • bf-manage-sitepwrmon
          • bf-manage-incidents
          • bf-telematics
          • bf-depot-sim
          • bf-manage-roaming
          • bf-support-microsite
          • bf-digital-twin
          • bf-schedule-creator
        • Overview
        • Internal Application Diagrams
        • Migration and Flags
        • Simulation Request Lifecycle
          • Index
          • bf-bnl-ui
          • bf-bnl-settings
          • bf-bnl-schedule-analysis-compute
          • bf-route-modelling
          • bf-schedule-creator
          • bf-digital-twin
        • Overview
        • Secrets and Env Strategy
        • Vendors and Local Dependencies
        • ADRs
        • Service Matrix
        • Cloud Dependencies
        • Ports and URLs
      • Onboarding
      • Daily Operations Runbook
        • Overview
        • Staging Hotfix Release
        • Production Hotfix Release
        • Terraform Plan Dry Runs
      • Troubleshooting
      • Testing Guide
    • Summary
    • System Design Reference
    • Project Goal
    • In Scope
    • Story Scope
    • Explicitly Out of Scope for This Project
    • Short-Term Delivery Notes
    • Backlog and Downstream Links

    Implementation Specification: BBA Microgrid Controller¶

    Summary¶

    This implementation specification defines the project-scoped delivery for the BBA Microgrid Controller milestone.

    It is an incremental delivery plan against the long-lived microgrid system design. It intentionally focuses on the smallest usable microgrid slice needed for the BBA milestone and leaves broader balancing, topology, and protocol work to later projects.

    System Design Reference¶

    • Primary system design: docs/system-design/microgrid/spec.md
    • Generic packet contract: docs/system-design/iot-sensor-packet/spec.md
    • BBA packet translation: docs/system-design/bba-microgrid-controller/generic-packet-translation.md

    Project Goal¶

    Deliver a minimal microgrid slice in BetterFleet Manage that provisions one canonical microgrid record per depot and shows externally reported PEAK_SHAVING and DER state on the Manage UI Microgrid card.

    In Scope¶

    • Canonical microgrid identity, one persisted microgrid record per depot, and depot-to-microgrid read model.
    • Auto-create and backfill of microgrids for existing depots that already have one or more top-level circuits.
    • Automatic microgrid creation as part of depot creation.
    • Singular microgrid read and resync API plus a System Admin microgrid view that shows grid connections and downstream legacy electrical structure derived from the depot's current circuits.
    • Automatic sync of persisted first-level GRID_CONNECTION nodes when top-level circuits are created, reparented, renamed, or deleted.
    • External PEAK_SHAVING and DER capability-status ingest, append-only history in shared event infrastructure, and latest derived read state.
    • Reuse of device sensor-action configuration for the first external-controller source binding, including a new Update Microgrid State action generated through the existing sitepwrmon capability/config flow.
    • Microgrid card visibility for those capability states in Manage UI, even for depots that do not have a local PowerSource record.

    Story Scope¶

    • All stories in stories.md in this folder.

    Explicitly Out of Scope for This Project¶

    • Protocol-agnostic OperatingEnvelope handling.
    • Hierarchical load balancing using complex microgrid structures.
    • Persistent topology management, topology editing, or topology conflict workflows.
    • Node or aggregate limit management.
    • OSCP integration and partner-profile behavior.
    • Depot simulator enhancements.

    Short-Term Delivery Notes¶

    • This project establishes the minimal canonical microgrid boundary used by later Vector DERMS and complex circuit load-balancing work.
    • The canonical depot microgrid created here becomes the anchor point for later derived complex electrical structures used by load balancing.
    • This milestone persists the initial first-level GRID_CONNECTION nodes sourced from the depot's top-level circuits and leaves deeper topology derived from legacy data for later projects.
    • Current bootstrap/admin APIs are intentionally depot-scoped locator endpoints (GET/POST /api/depot/{depot_id}/microgrid...) while supported cardinality remains 1 depot = 1 microgrid; this does not change canonical entity identity from microgrid_id.
    • Current topology updates in this milestone are system-owned synchronization from legacy circuit changes and explicit Resync, not operator-authored topology editing. version is therefore a persisted change marker in this milestone rather than a client-supplied optimistic-lock token.
    • Sync from legacy circuit changes is implemented synchronously inside the same service boundary as an interim migration pattern; event-driven/outbox propagation is reserved for later cross-context evolution when broader microgrid-native workflows exist.
    • The current persisted root-level node restriction in this milestone is intentionally narrow: first-level nodes are GRID_CONNECTION nodes sourced from legacy top-level circuits. This is a BBA implementation constraint, not a permanent microgrid-domain invariant.
    • Existing circuit-centric load-balancing behavior remains in place for this milestone.
    • The first external status source is bf-manage-sitepwrmon.
    • Phase 1 capability status remains whole-microgrid scoped even though the target design supports node-scoped control points later; the current ingest route does not yet expose caller-supplied node_id.
    • Phase 1 stores runtime capability history in shared event_store / event_outbox domain-event infrastructure while keeping CapabilityControlPoint ownership in microgrid-side state.
    • Phase 1 derives the latest visible capability status directly from stored microgrid domain events rather than writing a dedicated microgrid capability projection table.
    • The first external status payloads for PEAK_SHAVING and DER are boolean true / false values. The implementation should normalize them into UI-facing ON / OFF operational status while retaining raw values in status detail for audit/debug use.
    • The first configuration UX for enabling external capability-status ingest should reuse device sensor-action configuration rather than introduce a separate microgrid capability-control-point admin screen.
    • External microgrid-controller sensor actions must work when site_model_name = None; direct sensor-action routing must therefore not depend on gateway model output_translation.
    • In this milestone, sensor-action-based power source updates resolve their target asset by direct electrical binding: first one power source on the sensor device's linked circuit, then one battery power source in the same depot, then gateway output_translation as a compatibility fallback.
    • Model-driven outputs from gateway site models such as utilise_gen_capacity_dynamic continue to use gateway output_translation.
    • Phase 1 assumes sites that rely on direct depot-level fallback have one battery power source in the depot. Sites that do not satisfy that assumption require remediation or later explicit power_source_id binding support.
    • The load-page Microgrid card rollout for PEAK_SHAVING and DER capability status is currently gated behind the new-microgrid-fields-load-chart feature flag.
    • Phase 1 supports one active external source device per capability type per whole-microgrid scope. Additional sources for the same capability should be treated as configuration conflict until multi-source ownership is designed explicitly.
    • Phase 1 does not yet enforce generic inbound idempotency by source_event_ref; duplicate deliveries may append duplicate stored events temporarily until a shared inbox/receipt mechanism exists, but the latest visible status remains derived from the most recently folded event history.

    Backlog and Downstream Links¶

    • Downstream load-balancing work is tracked under docs/artifacts/active/complex-circuit-load-balancing/.
    • Microgrid stories not assigned to an active project are tracked under docs/artifacts/backlog/microgrid/stories.md.
    Made with Material for MkDocs