Complex Circuit Load Balancing Deliverables (Stories)¶
Context Summary¶
- Product area: BetterFleet Manage.
- Primary systems:
bf-manage-core(microgrid derivation + hierarchical balancing),bf-manage-web(operator UX), and seeded or simulator-backed site scenarios for demonstrable outcomes. - Scope basis:
docs/work/active/complex-circuit-load-balancing/spec.md. - Delivery intent: thin, demonstrable slices that show visible value through load-balancing behavior or UI state, while allowing the smallest package-level foundation slice when it is the clean prerequisite for later product-visible work.
- MVP focus: build a derived in-memory complex microgrid structure over existing site data, anchored to the persisted microgrid as the site root and the persisted first-level
GRID_CONNECTIONnodes created in BBA, then use explicit existing circuit and charger ratings to enforce hierarchical limits during rebalance before investing in persistent topology-management features.
Load-Balancer Complex Power Node Support for Connector Strategies¶
User Story¶
As a load-balancing engineer, I want the load-balancer package to accept a hierarchical complex power node structure derived from the site microgrid so that connector-based strategies can allocate power against realistic electrical constraints without depending on BetterFleet's full microgrid model.
Linear Ref¶
COR-10
Dependencies¶
- Microgrid Provisioning and Management
Acceptance Criteria¶
- The load-balancer package accepts a hierarchical power-node input shape that mirrors the complex microgrid structure required for balancing while containing only the fields needed for allocation and constraint evaluation.
- The power-node input can represent at least the microgrid root, first-level
GRID_CONNECTIONnodes, charger-circuit branches, and downstream charging assets with their effective electrical limits and parent-child relationships. - Connector-based load-balancing strategies use the hierarchical power-node input when calculating allocations.
- For a WA-PTA-style hierarchy, package-level allocation logic respects grid-connection, charger-circuit, and downstream charging limits together.
- Existing supported connector-based behavior remains deterministic for sites that do not require the richer hierarchy.
Complex Microgrid Representation, Display, and Load-Balancer Projection¶
User Story¶
As an operations user, I want BetterFleet to represent and display a complex microgrid and project it into the load-balancer power-node structure so that complex sites can be inspected in-product and passed through the existing load-balancing flow.
Linear Ref¶
COR-11
Dependencies¶
- Load-Balancer Complex Power Node Support for Connector Strategies
Acceptance Criteria¶
- For a site with a persisted microgrid, the product expands the representation beyond the persisted root and first-level
GRID_CONNECTIONnodes to derive enough complex structure to represent charger-circuit branches and downstream charging assets. - A read-only Manage UI surface or diagnostic summary shows enough of the complex microgrid hierarchy for an operator to confirm the expected grid-connection-to-branch-to-charger structure without editing it.
- The product derives a load-balancer power-node structure as a subset projection of the complex microgrid and passes that projection to the existing load-balancing entry points.
- Limits in the projected power-node structure come from the applicable existing rating sources used by the current load-balancing path: top-level circuit default/safe operating capacities, downstream circuit default/safe operating capacities, and charge-point or connector maximum ratings.
- When an active
OperatingEnvelopeis present, the projected power-node structure uses the most restrictive effective constraint before invoking the load-balancer package. - If the existing site data cannot be resolved into a valid complex microgrid or load-balancer projection, the product returns a deterministic validation or unsupported-topology outcome.
Load-Balancer Complex Power Node Support for Charger-Based Strategies¶
User Story¶
As a load-balancing engineer, I want charger-based strategies to use the same hierarchical complex power node structure as connector-based strategies so that sites using charger control modes enforce realistic grid and branch constraints during rebalance.
Linear Ref¶
COR-35
Dependencies¶
- Complex Microgrid Representation, Display, and Load-Balancer Projection
Acceptance Criteria¶
- For charger-based strategies, the load-balancer package accepts and uses a hierarchical power-node input shape derived from the complex microgrid with charge-point leaves and the same ancestor grid-connection and charger-circuit structure already used for connector-based strategies.
- For a WA-PTA-style hierarchy, charger-based allocation respects grid-connection, charger-circuit, and charge-point limits together.
- The current product load-balancing entry points pass the existing complex-microgrid projection into charger-based rebalance flows using the same rating sources already used by the current charger-based path.
- Existing charger-based behavior remains deterministic for sites that do not require the richer hierarchy or where no supported complex topology projection is available.
- Connector-based strategies continue to behave unchanged when charger-based support is added.
Microgrid Status Summary View¶
User Story¶
As an operations user, I want a Microgrid status summary view for complex sites so that I can see the latest cycle outcome and which part of the electrical hierarchy is constraining the site.
Linear Ref¶
COR-12
Dependencies¶
- Complex Microgrid Representation, Display, and Load-Balancer Projection
Acceptance Criteria¶
- Opening the Microgrid status summary for a complex site shows the latest cycle outcome, current site-level allocation, and current branch-level constraint context.
- When a grid or charger-circuit node constrains the cycle, the summary identifies that node and shows limit-versus-demand context.
- Sites with no completed rebalance yet render a deterministic empty summary rather than a broken or blank view.
- Refreshing after a new rebalance shows the latest completed outcome consistently.
Manage UI Cycle and Breach Visibility¶
User Story¶
As a support operator, I want cycle outcomes and hierarchical breach context visible in UI so that I can troubleshoot complex-site balancing without backend log access.
Linear Ref¶
COR-13
Dependencies¶
- Complex Microgrid Representation, Display, and Load-Balancer Projection
Acceptance Criteria¶
- UI status surfaces show cycle outcome (
APPLIED,CURTAILED,REJECTED) for a selected complex microgrid. - UI breach or constraint surfaces show deterministic reason code and the node context that constrained the cycle.
- When a charger-circuit branch constrains downstream chargers, the UI makes that relationship visible without requiring raw topology inspection.
- Refreshing the UI after rebalance reflects the latest cycle state without manual data reshaping.
WA-PTA Complex Load-Balancing Validation Scenario¶
User Story¶
As a QA or delivery stakeholder, I want a repeatable WA-PTA-style validation scenario so that the complex hierarchical balancing behavior can be demonstrated end-to-end.
Linear Ref¶
COR-14
Dependencies¶
- Complex Microgrid Representation, Display, and Load-Balancer Projection
Acceptance Criteria¶
- A seeded or simulator-backed site scenario represents one grid connection, four charger circuits, and four chargers per charger circuit.
- Driving demand above charger-circuit and grid limits produces visible curtailment that matches the hierarchical balancing model.
- Re-running the same scenario yields the same visible site and branch allocation outcomes.
- Scenario artifacts or captured simulator outputs are sufficient for QA and stakeholder review without requiring backend log inspection.