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
    • Process
    • Products
    • Reference
    • Decisions
    • Work
    • Operations
    bf-dev
    • Home
      • Process Handbook
      • BetterFleet Workflow Map
      • Product Development System
      • Product Engineering Workflow
        • Process Workflows
        • Work Intake and Weekly Planning
        • Product Engineering Workflow in Linear
        • Product Engineering Delivery
        • Agent Guidance
        • Workflow
        • Skills
        • Skill Sources
        • Process Guides
        • GitLab Feature Flags
        • In-App Docs Authoring
        • Release Notes
        • Process Templates
        • Release Plan: <title>
      • Process Publishing
      • Product overview
        • General Reference
          • Core Domain Training
          • System Topology
          • Two-Axis Ontology Model
          • Ontology Primer
          • Worked Example
          • Evidence, Ownership, and Lineage
          • Energy Management
          • Standards and Protocol Map
          • Charging, Roaming, and Commercial Model
          • Charge Planning and Operations
          • Cross-Cutting Domains
          • Domain Coverage Matrix
        • BetterFleet Product Ontology
        • Core Operations Data Ontology
        • BetterFleet R&D Plan
        • Index
        • Architecture
        • Manage Product Capabilities
        • Manage Data and State
        • Manage Service Interaction Flows
        • Manage Reference
        • Manage Internal Application Diagrams
          • Manage Authorization And Permissions
          • bf-manage-core Auth and Authorization Model
          • Manage Authorization and Permissions
          • bf-manage-web Auth and Permission Model
          • Manage Service Catalog
          • bf-depot-sim
          • bf-digital-twin (Manage Role)
          • bf-fleet-health
          • bf-manage-connect
          • bf-manage-core
          • bf-manage-incidents
          • bf-manage-roaming
          • bf-manage-sitepwrmon
          • bf-manage-web
          • bf-schedule-creator (Manage Role)
          • bf-support-microsite
          • bf-telematics
        • Index
        • Architecture
        • Plan Reference
        • Plan Internal Application Diagrams
        • Plan Migration and Flags
        • Plan Simulation Request Lifecycle
          • Plan Service Catalog
          • bf-bnl-schedule-analysis-compute
          • bf-bnl-settings
          • bf-bnl-ui
          • bf-digital-twin (Plan Role)
          • bf-route-modelling
          • bf-schedule-creator (Plan Role)
      • Where to Ask Product Questions
      • Reference
        • Platform Reference
        • Platform Architecture
        • Script Runtime Model
        • Compose Profiles and Modes
        • Repository Map
        • Monolithic Git Transition FAQ
        • Monolithic Git Sizing
        • CI and Release Integration
        • Shared Reference
        • Shared Infrastructure Architecture
        • Secrets and Env Strategy
        • Vendors and Local Dependencies
        • System Reference
        • Cloud Data Dependencies
        • Ports and URLs
        • Service Matrix
          • API Docs
          • OCPI API Docs
          • OCPP API Docs
          • OSCP API Docs
          • VDV API Docs
          • Yard State API Docs
        • System Design
        • System Design: BBA Microgrid Controller Generic Packet Translation
        • System Design: Depot Simulation
        • System Design: IoT Sensor Packet
        • System Design: Microgrid Energy Orchestration
          • System Design: OCPP Profile 3 And ISO 15118 PKI
          • Architecture: BetterFleet OCPP Profile 3 and ISO 15118 PKI
          • Specification: BetterFleet OCPP Profile 3 and ISO 15118 Certificate Lifecycle Management
          • System Design: On-Prem Control
          • Challenge
          • Specification: BetterFleet On-Prem Continuity Control
          • System Design: OSCP
          • OSCP Protocol Documentation
          • Depot Sim Testing Requirements
          • System Design: OSCP Flexibility Provider Domain
      • Decisions
        • Architecture Decision Records
        • 0001 - Record architecture decisions
        • 0002 - Cognito for Authentication and Authorisation
        • 0003 - AWS Amplify for Authentication
        • 0004 - DynamoDB for default database
        • 0005 - Data Persistence
        • 0006 - Trunk-Based Development
        • 0007 - Generalised principle for automation
        • 0008 - Naming Repositories, Services, and URLs
        • 0009 - Use Timezone Aware DateTimes and UTC
        • 0010 - Use semantic release
        • 0011 - Centralized feature flag repository
        • 0012 - Use Named Exports in Storybook
        • 0013 - RESTful TITLE GraphQL
        • 0014 - Service Granularity
        • 0015 - Async/co-routine exception handling pattern
        • 0016 - Logging & log levels
        • 0017 - Instantiated Models
        • 0018 - Repository Pattern for Database Access
        • 0019 - Use of Design Tokens in TypeScript React Application
        • 0020 - API backwards compatibility and versioning
        • 0021 - Alembic Migration strategy
        • 0022 - Consistent react-hook-form usage
        • 0023 - Domain Event-Driven Architecture
        • 0024 - Domain Event Bus Tech Stack
        • 0025 - No enum types in DB table columns
        • 0026 - In-Memory Ormar Stores for Repository testing
        • 0027 - Storing Tab State in Query and Local Storage
        • 0028 - Adopt OpenTelemetry Semantic Conventions for Structured Logging
        • 0029 - Adopt RFC 9457 for HTTP Error Responses
        • 0030 - Use GitLab registry and Terraform state for ECS services
        • 0031 - Adopt DDD, Hexagonal Architecture, and CQRS for Python Domain Services
      • Work
        • Active Work
          • Work: Bba Microgrid Controller
          • Implementation Specification: BBA Microgrid Controller
            • 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
          • BBA Microgrid Controller Deliverables (Stories)
          • Work: BFDev Monolithic Git
          • Challenge
          • Specification: BFDev Monolithic Git v2
          • BFDev Monolithic Git v2 Stories
          • Work: Complex Circuit Load Balancing
          • Implementation Specification: Complex Circuit Load Balancing
          • Complex Circuit Load Balancing Deliverables (Stories)
            • COR-10 and COR-11 Consolidation Review
          • Work: Dispatch Reliability and Reconciliation
          • Challenge
          • Specification: Dispatch Reliability and Reconciliation
          • Dispatch Reliability and Reconciliation (Unit User Stories)
            • Dispatch populated vehicle cards grey surface snapshot
            • Dispatch Visual Review
          • Work: Enable Scheduled Managed Charger Access
          • Challenge: Enable Scheduled Managed Charger Access
          • Specification Exploration Dossier: Enable Scheduled Managed Charger Access
          • Specification Review: Enable Scheduled Managed Charger Access
          • Specification: Enable Scheduled Managed Charger Access
          • Work: Guided Cut-Off and Release Orchestration
          • Specification: Guided Cut-Off and Release Orchestration
          • Guided Cut-Off and Release Orchestration (Unit User Stories)
          • Work: Production Deployment Validation
          • Challenge
          • Work: Scheduled Report Parity
          • Specification: Scheduled Report Parity
          • Work: Telematics
          • Telematics EventBridge Path
          • Telematics Ingress Architecture
          • Specification: Telematics Migration into bf-manage-core with 5-Minute Freshness and Health Visibility
          • Telematics Core Migration MVP (Implementation-Time BDD)
          • Work: Vector Derms
          • Implementation Specification: Vector DERMS
          • Vector DERMS Deliverables (Stories)
          • Work: Visiting Vehicle Charging Visibility
          • Specification: Visiting Vehicle Charging Visibility
          • Visiting Vehicle Charging Visibility (Unit User Stories)
          • Work: Workspace Owned Stripe Roaming
          • Specification: Workspace-Owned Stripe Credentials for Roaming Payments
        • Backlog Work
          • Work: Microgrid
          • Microgrid Backlog Stories
          • Work: Mobile Ops Companion
          • Challenge
          • Specification: Mobile Operations Companion v1
          • Mobile Operations Companion Deliverables (Stories)
          • Work: Oscp
          • OSCP Backlog Stories
        • Archived Work
          • Work: Code Canonical Orchestration
          • Challenge
          • Specification: Product Engineering Workflow
          • Product Engineering Workflow Deliverables (Unit User Stories)
          • Work: Release Notes Automation
          • Release Plan: Release Notes Automation
          • Release Notes Automation Backlog Stories
      • Operations
      • Onboarding Runbook
        • Operations Runbooks
        • Production Hotfix Release
        • Staging Hotfix Release
        • Manage Staging Release Validation
        • Terraform Plan Dry Runs
        • Operations Tooling
        • Code Indexing
        • Operations Evidence
        • Database Restoration Test Report
      • Daily Operations Runbook
      • Testing Guide
      • Troubleshooting
    • 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
    1. Home
    2. Work
    3. Active
    4. Bba microgrid controller

    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/reference/system-design/microgrid.md
    • Generic packet contract: docs/reference/system-design/iot-sensor-packet.md
    • BBA packet translation: docs/reference/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/work/active/complex-circuit-load-balancing/.
    • Microgrid stories not assigned to an active project are tracked under docs/work/backlog/microgrid/stories.md.
    Made with Material for MkDocs
    BFDev Docs Assistant
    New conversation?
    Ask one focused question at a time, this helps the assistant provide accurate answers about what's been implemented in BetterFleet.