System Design: Microgrid Energy Orchestration¶

Solution Summary¶

Microgrid models a site's electrical system as a rooted electrical-node tree with node-linked source assets. It supports load management, energy management, optimisation, and operational visibility. Load balancing and hierarchical limit enforcement run on top of this model. circuit contracts remain compatibility aliases into Microgrid behavior.

This document defines the system design and reference contracts for the microgrid solution.

• Microgrid model: define microgrid_id as the primary identifier. Microgrid is the site root. MicrogridNode records form the child tree. The model must work across API, domain, and UI.
• Node Limit and Envelope model: define baseline node caps, operating envelopes, aggregate caps, and fallback demand rules. Use one deterministic constraint evaluation path.
• Capability Control Point model: define capability type, enablement state, control source, target node, and external configuration references for each control point. Load balancing and hierarchical limits remain the enforced runtime behavior. The capability taxonomy can grow without changing topology.
• Capability Status model: define append-only capability status domain events and a derived latest-status read model. Keep configuration separate from live state.
• Capacity Constraint Policy: define feeder-circuit compatibility projection, synchronous get_effective_circuit_capacity reconciliation, and policy-driven fallback behavior. Operator surfaces and legacy load-balancing paths read the same constraint state.
• Balancing Cycle: define cycle inputs, outputs, reason-code precedence, and audit fields. Execution must stay deterministic and debuggable.
• Depot Simulator updates: add microgrid-node topologies, telemetry degradation patterns, and compatibility-path triggers. This supports system-level validation.
• Compatibility Matrix: map circuit-centric APIs, events, and jobs to Microgrid contracts. Circuit consumers keep working without changing Microgrid ownership.

1. Summary¶

Problem¶

The product needs a Microgrid-based representation of the site electrical system. It must support hierarchical limits, broader energy capability coverage, operator visibility, and compatibility with circuit-centric consumers.

Goal¶

• Define the conceptual system design for microgrid topology, balancing, limits, compatibility behavior, and operator visibility.
• Use microgrid_id as the primary identifier across Microgrid contracts, while preserving circuit-driven compatibility entry points where they remain part of the product surface.
• Specify deterministic balancing decisions and auditable breach behavior.

Design Outcomes¶

• Balancing interfaces are microgrid-scoped, with optional subtree scope where a specific node boundary is required.
• Depot-scoped operator APIs may resolve the Microgrid through depot_id when depot identity is the operational locator.
• Legacy circuit flows have explicit translation and compatibility-projection behavior.
• Operating envelopes are Microgrid state. Legacy circuit capacity is a derived compatibility effect for managed feeder circuits.
• Operating-envelope lifecycle transitions are scheduler-driven. Synchronous get_effective_circuit_capacity reconciliation protects rebalance-time correctness.
• Requirement-to-verification mapping is complete and test-plannable.
• Depot simulator coverage supports end-to-end system testing of topology, limits, fallback, envelope lifecycle, and compatibility paths.

System Capabilities¶

• Microgrid domain model: introduce Microgrid, MicrogridNode, CapabilityControlPoint, CapabilityStatusEvent, CapabilityStatusProjection, NodeLimit, and OperatingEnvelope. Use one model across API, domain, and UI.
• Topology rules: define electrical tree authority, cycle/orphan protections, and versioned edits.
• Balancing contract: define a validate-before-allocate cycle with deterministic precedence and reason codes.
• Capability map: define a multi-capability vocabulary with load balancing as the enforced runtime scope in this design.
• OperatingEnvelope: define a protocol-agnostic inbound envelope model, lifecycle audit model, and active-envelope visibility. External protocol adapters must constrain Microgrid behavior without storing protocol-specific identifiers or foreign keys in Microgrid.
• Compatibility: define API, event, and scheduler translation from circuit_id to microgrid_id + node_id, plus projection into legacy circuit capacity.
• Depot Simulator: extend simulator scenarios for microgrid-node structures, limit policies, and degraded telemetry.
• Operator Visibility: define cycle status, breach payload semantics, and effective circuit-capacity visibility.

Scope (In)¶

• Ubiquitous language and conceptual model updates for microgrid-centric balancing.
• Public interface and event contract definitions (conceptual).
• Compatibility behavior for circuit-centric contracts.
• Deterministic policy invariants and verification mapping.
• Depot simulator enhancements needed for system-level tests.

Scope (Out)¶

• DB schema and low-level storage design.
• Low-level power electronics/control-loop implementation details.
• Final UI wireframes and visual design system specifics.

Architectural Guardrails¶

• The design must support one microgrid containing multiple grid connections and multiple independently managed subtrees without reshaping the core microgrid boundary.
• Capability taxonomy must allow adding peak shaving and optimization without changing core topology contracts.
• Compatibility behavior must remain removable without changing Microgrid ownership or contract semantics.
• External capability configuration owned by other bounded contexts must stay outside the microgrid write model and be referenced opaquely rather than linked by relational foreign keys.

2. Users and Use Cases¶

Primary Personas¶

High-Level Use Cases (Capability Scale)¶

• As an operator, I can configure one microgrid with a node hierarchy and node-linked source assets without creating invalid topology states.
• As a scheduler/system actor, I can run one balancing cycle per microgrid and receive deterministic outcomes.
• As an integration client, I can continue using circuit APIs through compatibility aliases and receive equivalent microgrid behavior.
• As an observer, I can inspect cycle and breach outputs with deterministic reason codes and audit metadata.
• As a test engineer, I can run system-level simulator scenarios that validate microgrid topology rules, limit enforcement, and compatibility translation.

Edge Cases and Failure Modes¶

• Reparent operation introduces a topology cycle.
• Node is detached from root (orphan).
• Aggregate cap breached while all individual nodes remain below local caps.
• Telemetry missing/stale for one or more nodes.
• Legacy circuit ID has no resolvable microgrid alias.
• Concurrent topology edits produce version conflict.

3. Conceptual Model Terms and Decisions¶

Key Terms¶

Decision Ledger¶

4. Domain Model and Eventstorming (Conceptual)¶

Bounded Context and Ubiquitous Language¶

• Bounded context: Microgrid Energy Orchestration.
• Core actors: Operator, Scheduler, Telemetry Ingest, External Protocol Adapter, Compatibility Adapter.
• Core commands: update topology, update node limits, update capability control point, append capability status event, submit operating envelope, request rebalance.
• Core events: topology updated, node limit updated, capability control point updated, capability status recorded, operating envelope received, operating envelope lifecycle evaluated, legacy capacity projected, cycle evaluated, breach detected, allocation applied.

Primary Access Patterns¶

• Physical Topology View (Tree)
  • Uses the node hierarchy to validate and enforce electrical flow constraints, such as fuse and grid-connection envelopes.
  • Evaluates all enforceable node limits and ancestor constraints.
• Operational Collection View (Resource Sets)
  • Uses collection-based queries, such as all BESS assets and charge points in a subtree or logical group, for energy-management calculations and optimization.
  • Can generate candidate strategies without depending on tree traversal mechanics.
  • Any candidate action that affects power allocation must still pass physical topology and node-limit validation before apply.

Aggregates and Entities (Conceptual)¶

• MicrogridAggregate:
  • Owns child node tree, capability control points, active node limits, and active operating-envelope references.
  • Owns balancing-cycle execution boundary.
• MicrogridNode:
  • Represents electrical structure and node-level policy assignment.
  • Supports reparenting with cycle/orphan protections.
• NodeLimit:
  • Defines baseline node constraints and fallback behavior.
• CapabilityControlPoint:
  • Defines capability identity, control ownership, target node context, and any opaque external configuration reference needed to resolve capability-owned config outside the microgrid boundary.
• CapabilityStatusEvent:
  • Immutable runtime status event reported by local or external control paths.
• CapabilityStatusProjection:
  • Latest runtime status read model derived from status events for read-side consumers.
  • May be materialized directly or reconstructed from authoritative status events.
• OperatingEnvelope:
  • Represents a protocol-agnostic operating constraint for one node subtree within a microgrid.
  • Owns normalized effective window, envelope blocks, generic source reference metadata, active lifecycle state, target scope, and optional origin control-point reference for traceability.

Invariants and Business Rules (Normative)¶

1. Node hierarchy must form a single rooted acyclic tree, with Microgrid as the implicit root and one or more first-level GRID_CONNECTION child nodes beneath it.
2. Each node belongs to exactly one microgrid.
3. A source asset may be referenced by at most one node in the same microgrid.
4. Only nodes carry enforceable physical-limit constraints.
5. Balancing cycle must evaluate ancestor and aggregate constraints before allocation apply.
6. Effective demand source order is deterministic: measured, then fallback.
7. Cycle output reason codes must follow fixed precedence ordering.
8. Legacy circuit_id commands must resolve to exactly one microgrid_id and one target node_id.
9. Collection-view optimization outputs must be validated against node-limit constraints before apply.
10. Capability control point state is enabled or disabled; runtime operational status is represented as a free-form string in status events.
11. schedule_ref must be null for capability control points where control_source=EXTERNAL.
12. Each capability status event must reference an existing capability control point for the same microgrid.
13. Capability control points may target either the whole microgrid (node_id=null) or one node subtree.
14. At most one active capability control point may exist for the same microgrid_id + node_id + capability_type.
15. At most one active baseline node limit may exist for the same node_id + constraint_type.
16. Capability status events are append-only and immutable once accepted.
17. Latest capability status read state is derived from ordered status events and may be rebuilt from stream history.
18. Operating-envelope ingress must remain protocol-agnostic and must not require OSCP or other protocol-specific identifiers or cross-context foreign keys in the microgrid domain model.
19. Operating envelopes target one node subtree and must reference a valid node in the owning microgrid.
20. Active operating envelopes must be evaluated as effective constraints before allocation apply.
21. When a baseline NodeLimit and one or more active OperatingEnvelope records apply to the same node and constraint type, the effective constraint used for balancing must be the most restrictive active value.
22. Active operating envelopes for a managed GRID_CONNECTION node must project the effective envelope constraint to the mapped feeder circuit and must restore the non-envelope baseline deterministically when the envelope no longer applies.
23. Operating-envelope lifecycle transitions must be driven by scheduled evaluation at block boundaries and envelope expiry, while rebalance-time compatibility must be protected by synchronous get_effective_circuit_capacity reconciliation.
24. Capability control points may store opaque external configuration references for capability config owned outside microgrid, but microgrid must not require relational write-time foreign keys to those external config tables.
25. Capability status history and operating-envelope lifecycle history are separate audit concerns and must not be collapsed into one payload contract.

Effective Demand Resolution Rules (Normative)¶

For each checked scope (node or aggregate): 1. Use measured_demand_watts if telemetry is present, valid, and within freshness threshold. 2. Otherwise derive fallback_demand_watts from configured fallback policy inputs. 3. Set source_mode to MEASURED or FALLBACK_DERIVED. 4. Persist audit fields identifying source inputs and thresholds used.

Model Relationships¶

Abstract Class Relationships¶

classDiagram
    direction LR

    class Depot {
        +UUID depot_id
    }

    class Microgrid {
        +UUID microgrid_id
        +UUID depot_id
        +int version
    }

    class MicrogridNode {
        +UUID node_id
        +UUID microgrid_id
        +UUID? parent_node_id
        +string name
        +NodeType node_type
        +AssetType? attached_asset_type
        +UUID? attached_asset_id
        +NodeStatus status
        +int display_order
    }

    class CapabilityControlPoint {
        +UUID control_point_id
        +UUID microgrid_id
        +UUID? node_id
        +CapabilityType capability_type
        +CapabilityState state
        +ControlSource control_source
        +string? external_config_type
        +string? external_config_ref
        +object? local_config
    }

    class CapabilityStatusEvent {
        +UUID status_event_id
        +UUID microgrid_id
        +UUID control_point_id
        +UUID? node_id
        +string operational_status
        +datetime observed_at
    }

    class CapabilityStatusProjection {
        +UUID microgrid_id
        +UUID control_point_id
        +UUID? node_id
        +string latest_operational_status
        +datetime last_observed_at
        +ReadModel only
    }

    class NodeLimit {
        +UUID node_limit_id
        +UUID microgrid_id
        +UUID node_id
        +ConstraintType constraint_type
        +int limit_watts
        +LimitSourceType source_type
    }

    class OperatingEnvelope {
        +UUID envelope_id
        +UUID microgrid_id
        +UUID node_id
        +UUID? origin_control_point_id
        +EnvelopeType envelope_type
        +ConstraintType constraint_type
        +EnvelopeStatus status
    }

    Depot "1" --> "1" Microgrid : owns
    Microgrid "1" *-- "0..*" MicrogridNode : child nodes
    MicrogridNode "1" --> "0..*" MicrogridNode : child nodes
    Microgrid "1" --> "0..*" CapabilityControlPoint : defines
    CapabilityControlPoint "1" --> "0..*" CapabilityStatusEvent : records
    CapabilityControlPoint "1" --> "1" CapabilityStatusProjection : projects
    MicrogridNode "1" --> "0..*" NodeLimit : constrained by
    MicrogridNode "1" --> "0..*" OperatingEnvelope : receives
    CapabilityControlPoint --> MicrogridNode : targets 0..1 node
    CapabilityStatusEvent --> MicrogridNode : cached 0..1 node
    CapabilityStatusProjection --> MicrogridNode : cached 0..1 node
    NodeLimit --> MicrogridNode : targets 1 node
    OperatingEnvelope --> MicrogridNode : targets 1 node
    OperatingEnvelope --> CapabilityControlPoint : optional origin 0..1

MicrogridScope is not a first-class entity. Scope is represented everywhere as microgrid_id + node_id, where node_id identifies the subtree root for the command, envelope, projection, or compatibility mapping being evaluated.

Illustrative Topology Example¶

flowchart TD
    Depot[Depot] --> Microgrid[Microgrid<br/>microgrid_id<br/>depot_id]

    Microgrid --> GC1[MicrogridNode<br/>node_type=GRID_CONNECTION]
    Microgrid --> GC2[MicrogridNode<br/>node_type=GRID_CONNECTION]
    GC1 --> C1[MicrogridNode<br/>node_type=CIRCUIT]
    C1 --> CP1[MicrogridNode<br/>node_type=CHARGE_POINT]
    CP1 --> CON1[MicrogridNode<br/>node_type=CONNECTOR]

    GC1 -. attached_asset .-> CircuitAssetA[(Circuit)]
    GC2 -. attached_asset .-> CircuitAssetB[(Circuit)]
    C1 -. attached_asset .-> SubCircuitAsset[(Circuit)]
    CP1 -. attached_asset .-> ChargePointAsset[(Charge Point)]
    CON1 -. attached_asset .-> ConnectorAsset[(Connector)]

    Microgrid --> SiteCP[CapabilityControlPoint<br/>node_id=null]
    GC1 --> ScopedCP[CapabilityControlPoint<br/>node_id=grid_connection_node]
    SiteCP --> StatusEvent[CapabilityStatusEvent<br/>append-only history]
    SiteCP --> StatusProjection[CapabilityStatusProjection<br/>latest read model]
    ScopedCP --> StatusEvent
    ScopedCP --> StatusProjection

    GC1 --> NodeLimit[NodeLimit]
    GC1 --> OperatingEnvelope[OperatingEnvelope]
    C1 --> BranchLimit[NodeLimit]

Contract Definitions¶

Microgrid¶

• Microgrid is the site root.
• First-level child nodes are represented by MicrogridNode rows with parent_node_id = null.
• Row-level audit fields are intentionally omitted.
• Audit history is derived from domain events, compatibility streams, and audit streams.
• version is the row-level change marker used for deterministic mutation ordering.

MicrogridNode¶

• MicrogridNode is both the topology node and the attachment point for source-domain assets.
• A separate attached-asset entity is not part of the design.
• Managed compatibility scopes are anchored at first-level GRID_CONNECTION nodes.
• Deeper child structure, such as circuits, charge points, connectors, power sources, and virtual nodes, may participate in topology and visibility.

CapabilityControlPoint¶

Recommended uniqueness: one active control point per microgrid_id + node_id + capability_type.

• CapabilityControlPoint links node scope to capability identity.
• When another bounded context owns capability configuration, the control point stores an opaque external reference instead of a relational foreign key across contexts.

CapabilityStatusEvent¶

• control_point_id is the stable link for status history.
• microgrid_id, node_id, and capability_type are retained for query efficiency and audit readability.

CapabilityStatusProjection¶

• CapabilityStatusProjection is a read model, not a required writable microgrid-domain table.
• It may be materialized directly or reconstructed from authoritative status events.
• External-controller integrations may ingest boolean raw values and normalize them into stable operational-status strings such as ON and OFF, while retaining the raw source value in status_detail.

NodeLimit¶

NodeLimit is the baseline structural constraint for a node. Time-bounded or externally sourced overrides belong in OperatingEnvelope.

OperatingEnvelope¶

• OperatingEnvelope represents scheduled or externally sourced effective constraints applied on top of baseline NodeLimit values.
• Envelope receipt, withdrawal, expiry, and other lifecycle changes are audited independently from capability-status history.

OperatingEnvelopeBlock¶

Operating-Envelope Compatibility Policy¶

• OperatingEnvelope holds time-bounded externally sourced or operator-authored constraint state.
• Compatibility projection is permitted only when the envelope targets a managed first-level GRID_CONNECTION node that maps to exactly one feeder circuit.
• Active primary forecast envelopes determine the forecast-side limit while the source is healthy.
• If the forecast source is stale or offline, a valid FALLBACK envelope determines the forecast-side limit. If no valid fallback forecast exists, the circuit fail-safe capacity applies.
• If the source is healthy but the current primary forecast has no active block, the configured gap policy determines the forecast-side limit. The current implementation defaults to circuit default capacity.
• Active non-forecast envelopes such as overrides or TOU limits can further tighten the resolved forecast-side limit; the most restrictive active limit wins.
• Envelope receipt, withdrawal, and scheduled lifecycle evaluation are compatibility projection triggers. They may update the mapped feeder-circuit capacity and request legacy rebalance when the effective value changes.
• get_effective_circuit_capacity(circuit_id, occurred_at) is a synchronous rebalance-time guard. It may reconcile the mapped feeder-circuit capacity before TOU and allocation logic run, but it must update the circuit-facing effective value without requesting another rebalance.
• Compatibility projection trigger values are ENVELOPE_CHANGE, ENVELOPE_LIFECYCLE, and REBALANCE_GUARD.

Capability Type Semantics¶

Public Interfaces (Conceptual)¶

• microgrid_id is the primary entity identifier.
• Depot-scoped operator routes may resolve the Microgrid through depot_id when depot identity is the operational locator.
• Circuit-facing routes remain compatibility aliases only.

Operating-envelope ingestion is not a public microgrid HTTP concern in this design. External interfaces such as OSCP and future protocol adapters translate source payloads and submit OperatingEnvelope records through the internal MicrogridOperatingEnvelopeWritePort, targeted by microgrid_id + node_id. Operator-facing microgrid routes remain read and management oriented.

Operator-Facing and Core API Shape¶

Error and Status Semantics (Conceptual)¶

Compatibility Matrix¶

Rebalance and Breach Response Semantics¶

Cycle Result Payload (Conceptual)¶

Breach Payload (Conceptual)¶

Capability Status Event Payload (Conceptual)¶

Capability Status Latest-Read-State Payload (Conceptual Read Model)¶

Deterministic Reason-Code Precedence¶

1. TOPOLOGY_INVALID
2. TOPOLOGY_VERSION_CONFLICT
3. ANCESTOR_CAP_EXCEEDED
4. AGGREGATE_CAP_EXCEEDED
5. NODE_CAP_EXCEEDED
6. TELEMETRY_STALE_FALLBACK_USED
7. LEGACY_ALIAS_TRANSLATION_APPLIED

Interaction Flow¶

flowchart LR
  A[Operator or Scheduler] --> B[Command: Update Topology / Limits / Rebalance]
  B --> C[Policy Checks: Topology + Version + Limit Consistency]
  C -->|valid| D[Resolve Effective Demand]
  C -->|invalid| E[Reject Command with Deterministic Reason Code]
  D --> F[Evaluate Ancestor and Aggregate Constraints]
  F --> G{Feasible Allocation?}
  G -->|Yes| H[Apply Allocations]
  G -->|No| I[Apply Curtailment or Reject]
  H --> J[Publish Cycle Summary + Audit]
  I --> K[Publish Breach + Cycle Summary + Audit]

Event Timeline¶

timeline
  title Microgrid Balancing Event Timeline
  Topology Updated: Versioned topology accepted
  Node Limit Updated: Baseline node constraint changed
  Cycle Requested: Rebalance command accepted
  Demand Resolved: Measured or fallback demand selected
  Constraints Evaluated: Ancestor, node, and aggregate checks
  Allocation Applied or Rejected: Deterministic outcome generated
  Audit Published: Cycle summary and breach details emitted

Sequence Diagram: Operating Envelope Compatibility Lifecycle¶

sequenceDiagram
  participant Source as External Adapter or Operator
  participant API as Microgrid API
  participant Domain as Microgrid Domain
  participant Scheduler as Envelope Lifecycle Scheduler
  participant Compat as Legacy Circuit Compatibility

  Source->>API: Submit OperatingEnvelope(microgrid_id + node_id)
  API->>Domain: Validate envelope, target node, and blocks
  Domain->>Domain: Persist OperatingEnvelope
  Domain->>Compat: Project effective CONSUMPTION_CAP target to mapped feeder circuit when active
  Compat->>Compat: Update circuit capacity and trigger rebalance when the effective value changes
  Domain->>Scheduler: Schedule block-boundary and expiry refresh events
  Scheduler->>Domain: Evaluate lifecycle at boundary or expiry
  Domain->>Compat: Recompute projection or restore baseline
  Note over Compat: Rebalance-time get_effective_circuit_capacity may reconcile drift for now but must not trigger another rebalance

Event Dictionary¶

5. Requirements and Constraints¶

Functional Requirements¶

• FR-001: System must execute load balancing at the microgrid boundary, with optional subtree scope where a specific node boundary is required.
• FR-002: System must support hierarchical nodes with cycle-safe and orphan-safe topology edits.
• FR-003: System must enforce node limits and aggregate microgrid limits in the same balancing cycle.
• FR-004: System must compute effective demand using measured-first, derived fallback behavior.
• FR-005: System must validate all active limits before allocation apply.
• FR-006: System must publish breach and cycle-summary visibility for operators.
• FR-007: System must provide tree-based topology configuration and status visibility for nodes and their linked source assets.
• FR-008: System must preserve compatibility with circuit-centric integrations through explicit alias translation and projection policy.
• FR-009: Public contracts must use microgrid_id as the primary identifier.
• FR-010: Source-domain assets must be represented by node-linked asset references and not as topology parents outside the node tree.
• FR-011: Topology mutation APIs must enforce optimistic concurrency via topology version.
• FR-012: Cycle outputs must include deterministically ordered reason codes.
• FR-013: System must define capability types including load balancing, peak shaving, DER, and optimization.
• FR-014: Runtime enforcement in this design must be limited to load balancing and hierarchical limits.
• FR-015: Legacy circuit_id requests/events must translate to exactly one microgrid cycle.
• FR-016: Alias translation failures must return explicit reason codes and auditable records.
• FR-017: Depot simulator must support microgrid-node topology, policy, and degraded telemetry scenarios for system-level testing.
• FR-018: System must support two access patterns: physical topology view and operational collection view.
• FR-019: Collection-view optimization outputs must be validated against physical node-limit constraints before apply.
• FR-020: System must separate capability configuration (CapabilityControlPoint) from runtime status contracts (CapabilityStatusEvent and CapabilityStatusProjection) in public interfaces.
• FR-021: System must ingest and expose external runtime capability status for externally controlled capabilities.
• FR-022: schedule_ref in capability control points is valid only when control_source=LOCAL.
• FR-023: Capability status events must reference capability control points (CapabilityStatusEvent -> CapabilityControlPoint) for referential integrity.
• FR-024: Runtime capability status must be persisted as an append-only history stream of immutable status events.
• FR-025: System must expose a derived latest capability status read model for low-latency UI status-card reads.
• FR-026: System must provide a protocol-agnostic OperatingEnvelope write/read contract keyed by microgrid_id + node_id for externally sourced constraints.
• FR-027: Active operating envelopes must be validated and applied as node-scoped effective constraints during balancing and status evaluation.
• FR-028: System must synchronously resolve effective feeder-circuit capacity through get_effective_circuit_capacity before rebalance-time TOU and allocation logic run.
• FR-029: An active CONSUMPTION_CAP operating envelope for a managed GRID_CONNECTION node must project to exactly one mapped feeder circuit.
• FR-030: When the primary forecast source is stale or offline, system must use a valid fallback forecast if one is active, otherwise circuit fail-safe capacity.
• FR-031: When the primary forecast source is healthy but there is no active primary forecast value for now, system must apply the configured gap policy.
• FR-032: Operating-envelope lifecycle transitions must be evaluated by scheduled boundary processing rather than read-time mutation.
• FR-033: Operator reads must expose active operating envelopes and effective feeder-circuit capacity for managed nodes.

Non-Functional Requirements¶

• NFR-001: Balancing outcomes must be deterministic for identical inputs and topology version.
• NFR-002: Enforcement must continue under partial telemetry when fallback policy conditions are met.
• NFR-003: Breaches and cycle outcomes must be auditable with actor/source and timestamps.
• NFR-004: Uncertain states must fail safe toward lower allowable allocation.
• NFR-005: Compatibility translation behavior must be observable and idempotent per request.
• NFR-006: Compatibility behavior must follow published reason-code governance and keep Microgrid as the source of truth.
• NFR-007: Simulator scenarios must be reproducible and deterministic for regression runs.
• NFR-008: Capability runtime status must be timestamped and freshness-visible for operational use.
• NFR-009: Capability status-event ingest must support idempotency and deterministic projection behavior under duplicate/replayed inputs.
• NFR-010: Operating-envelope ingest must be auditable and idempotent by source reference.
• NFR-011: Scheduled operating-envelope lifecycle evaluation must be deterministic for identical envelope blocks and scheduled timestamps.

Constraints and Assumptions¶

• A-001: Supported cardinality is 1 depot = 1 microgrid.
• A-002: The primary contract key is microgrid_id; circuit_id is a compatibility alias only.
• A-003: Topology is an electrical tree of MicrogridNode records with node-linked source assets, not a fully generic arbitrary graph.
• A-004: Only node entities carry enforceable physical-limit constraints.
• A-005: Capability taxonomy is comprehensive, but the enforced runtime scope in this design is load balancing and hierarchical limits. Other capability types are status-visible placeholders.
• A-006: This specification defines domain contracts while leaving storage, framework wiring, and deployment details out of scope.

6. Interaction and Flow¶

User Journey¶

1. Operator configures topology and node limit policies for one microgrid and submits with the supplied topology version.
2. System validates structural and policy invariants.
3. Scheduler or operator requests rebalance for the microgrid.
4. System resolves effective demand, evaluates constraints, and determines feasible outcome.
5. System applies allocation or curtailment/rejection and returns deterministic reason codes.
6. System publishes cycle summary, breaches, and compatibility telemetry (if alias path used).
7. If operating-envelope or fallback-policy evaluation affects a managed GRID_CONNECTION node, envelope-change and scheduled lifecycle paths may project a new effective feeder-circuit capacity and trigger the legacy rebalance seam, while rebalance-time get_effective_circuit_capacity only reconciles drift for correctness and must not trigger another rebalance.

Sequence Diagram: Rebalance with Compatibility Alias¶

sequenceDiagram
  participant Client as Legacy or Microgrid Client
  participant API as Manage Core API
  participant Alias as Compatibility Adapter
  participant Domain as Microgrid Domain
  participant Alloc as Allocation Engine
  participant Audit as Event/Audit Stream

  Client->>API: POST /api/circuit/{circuit_id}/rebalance_load
  API->>Alias: Resolve circuit_id -> microgrid_id
  Alias-->>API: microgrid_id + alias_metadata
  API->>Domain: Request rebalance(microgrid_id)
  Domain->>Alloc: Evaluate demand + constraints + allocation
  Alloc-->>Domain: outcome + reason_codes + summaries
  Domain->>Audit: Publish cycle_completed + alias_applied (if used)
  Domain-->>API: cycle_result
  API-->>Client: 200 with mapped identifiers and reason codes

Flowchart: Topology Update Guardrails¶

flowchart TD
  A[Topology Update Request] --> B{Version matches?}
  B -->|No| C[409 TOPOLOGY_VERSION_CONFLICT]
  B -->|Yes| D{Cycle/Orphan Safe?}
  D -->|No| E[422 TOPOLOGY_INVALID]
  D -->|Yes| F[Apply Topology Version +1]
  F --> G[Publish microgrid.topology_updated]

7. Design Extensibility¶

• One microgrid may contain multiple GRID_CONNECTION child nodes and multiple independently managed scopes without changing the microgrid_id boundary defined here.
• Capability taxonomy is intentionally broader than the enforced runtime scope in this design, so PEAK_SHAVING, DER, and ENERGY_OPTIMISATION can become enforced later without reshaping topology contracts.
• Circuit-centric compatibility paths are removable adapters rather than part of the Microgrid ownership model.
• Storage schema, framework wiring, and deployment topology remain implementation concerns outside this system-design document.

8. Appendix A: Compatibility Reason Codes¶