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: Complex Circuit Load Balancing
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
          • 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
            • Summary
            • System Design Reference
            • Project Goal
            • In Scope
            • Story Scope
            • Planned Release Slices
            • Explicitly Out of Scope for This Project
            • Short-Term Delivery Notes
            • Dependency Notes
            • Backlog Link
          • 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
    • Planned Release Slices
    • Explicitly Out of Scope for This Project
    • Short-Term Delivery Notes
    • Dependency Notes
    • Backlog Link
    1. Home
    2. Work
    3. Active
    4. Complex circuit load balancing

    Implementation Specification: Complex Circuit Load Balancing¶

    Summary¶

    This implementation specification defines the project-scoped delivery for the Complex Circuit Load Balancing milestone.

    It is an incremental delivery plan against the long-lived microgrid system design. It focuses on using the microgrid concept to model more realistic electrical systems for load balancing, while keeping the MVP implementation pragmatic and close to existing persisted circuit, charge-point, and connector data.

    System Design Reference¶

    • Primary system design: docs/reference/system-design/microgrid.md

    Project Goal¶

    Deliver a microgrid-backed load-balancing MVP that can represent and balance a WA-PTA-style electrical structure where one or more grid connections feed multiple charger circuits and each charger circuit feeds multiple chargers, with hierarchical limits enforced across the whole site.

    In Scope¶

    • Build a richer in-memory microgrid balancing structure on top of the persisted microgrid created in BBA, using the microgrid itself as the root and the persisted first-level GRID_CONNECTION nodes sourced from the depot's top-level circuits.
    • Derive downstream charger-circuit, charger, and connector relationships in memory from existing persisted site data rather than introducing new topology tables in this MVP.
    • Use explicit existing rating sources as the authoritative hierarchical limits in this MVP:
      • top-level grid-connection circuit default/safe operating capacities for the first electrical layer beneath the microgrid
      • downstream circuit default/safe operating capacities for charger-circuit branches
      • charge-point and connector maximum ratings for downstream charging assets
    • Apply hierarchical rebalance behavior across grid connection, charger-circuit, and charger limits.
    • Show derived structure, cycle outcome, and branch or site constraint visibility through minimal product surfaces.
    • Demonstrate the behavior with seeded or simulator-backed scenarios suitable for QA and stakeholder review.

    Story Scope¶

    • All stories in stories.md in this folder.

    Planned Release Slices¶

    • Phase 1: Load-Balancer Package Enhancement
    • COR-10
    • Phase 2: Complex Microgrid Product Integration
    • COR-11
    • Phase 3: Customer Integration Testing
    • COR-14
    • Customer-specific integration or validation execution issues may be tracked only in Linear against this phase; they are not canonical repo stories.
    • Phase 4: Microgrid Status and Breach Visibility
    • COR-12
    • COR-13
    • Phase 5: Charger-Based Strategy Parity
    • COR-35

    Explicitly Out of Scope for This Project¶

    • Operator-authored topology editing.
    • Persistent microgrid topology tables, topology versioning, or topology conflict workflows.
    • Dedicated node or aggregate limit management UI.
    • Legacy circuit compatibility paths and TOU migration work.
    • Telemetry-fallback hardening beyond what is needed for the MVP balancing flow.

    Short-Term Delivery Notes¶

    • The MVP keeps the persisted Microgrid record as the stable site root, uses the persisted first-level GRID_CONNECTION nodes created in BBA, and derives the richer downstream balancing structure at read or evaluation time rather than persisting a full editable topology model.
    • Existing circuit, charge-point, and connector configuration remains the source of truth for physical ratings and electrical relationships in this phase.
    • In the current integrated path, the derived power-node projection is consumed by connector-based load-balancing strategies. Charger-based strategies still follow the existing charger-allocation path.
    • Charger-based parity for the same complex projection is tracked as a separate follow-on story in this project.
    • This project provides cross-project dependencies to the Vector DERMS milestone for microgrid status and cycle-visibility surfaces.

    Dependency Notes¶

    • This project builds on the microgrid provisioning, persisted microgrid record, and first-level persisted GRID_CONNECTION nodes delivered in docs/work/active/bba-microgrid-controller/.
    • Later OperatingEnvelope work remains owned by the Vector DERMS project and related follow-on microgrid stories. It is not a delivery dependency for COR-10 or COR-11.

    Backlog Link¶

    • Deferred 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.