Layered Architecture

EnerOS adopts a strict five-layer architecture, from top to bottom: Application Layer, Agent Runtime, Power-Native Kernel, Real-Time Safety Gateway, and Infrastructure. Each layer can only depend on lower layers, and cross-layer calls and reverse dependencies are prohibited, enforced through Cargo workspace dependency constraints at compile time.

Design Principles

Architecture Layer Overview

┌─────────────────────────────────────────────────────────────────────┐
│  L5  Application Layer                                               │
│      Dispatch · Operations · Trading · Planning · Efficiency ·      │
│      Self-healing · Digital Twin                                     │
│      [DispatchAgent] [OperationAgent] [TradingAgent]                │
│      [PlanningAgent] [SelfHealingAgent] [ForecastAgent]             │
├─────────────────────────────────────────────────────────────────────┤
│  L4  Agent Runtime                                                   │
│      7 domain Agents · Multi-agent collaboration ·                   │
│      Memory/Tools/Reasoning/Learning                                 │
│      [eneros-agent] [eneros-reasoning] [eneros-memory]              │
│      [eneros-tool] [eneros-ai] [eneros-twin] [eneros-nl]            │
├─────────────────────────────────────────────────────────────────────┤
│  L3  Power-Native Kernel                                             │
│      Topology · Power Flow · Constraints · Equipment ·               │
│      Time-series · Analysis · Events                                 │
│      [eneros-topology] [eneros-powerflow] [eneros-constraint]       │
│      [eneros-equipment] [eneros-timeseries] [eneros-analysis]       │
│      [eneros-eventbus] [eneros-cnpower] [eneros-emtp]              │
├─────────────────────────────────────────────────────────────────────┤
│  L2  Real-Time Safety Gateway                                        │
│      mTLS · CA · IDS · Audit · Compliance · Gateway · Trust         │
│      [eneros-gateway] [eneros-trust] [eneros-ids]                   │
│      [eneros-audit] [eneros-compliance]                             │
├─────────────────────────────────────────────────────────────────────┤
│  L1  Infrastructure                                                  │
│      OS services · Network · Storage · Multi-region ·               │
│      Multi-tenant · Protocols · Devices                             │
│      [eneros-os] [eneros-network] [eneros-multiregion]              │
│      [eneros-tenant] [eneros-scada] [eneros-device]                 │
│      [eneros-protocol-*] [eneros-perf] [eneros-core]               │
└─────────────────────────────────────────────────────────────────────┘

Inter-Layer Data Flow

                 ┌──────────────────┐
                 │   User / SCADA   │
                 └────────┬─────────┘
                          │ REST / GraphQL / WebSocket / SSE
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│ L5 Application Layer                                             │
│   DispatchAgent.plan() → TradingAgent.bid() → ...               │
└────────┬────────────────────────────────────────────────────────┘
         │ Agent SDK calls (system_call)
         ▼
┌─────────────────────────────────────────────────────────────────┐
│ L4 Agent Runtime                                                 │
│   lifecycle / orchestrator / reasoning / memory / tool           │
└────────┬────────────────────────────────────────────────────────┘
         │ Kernel system calls (Kernel API)
         ▼
┌─────────────────────────────────────────────────────────────────┐
│ L3 Power-Native Kernel                                           │
│   topology.analyze() → powerflow.solve() → constraint.check()   │
└────────┬────────────────────────────────────────────────────────┘
         │ Command dispatch (Command)
         ▼
┌─────────────────────────────────────────────────────────────────┐
│ L2 Real-Time Safety Gateway                                      │
│   gateway.execute_command() → trust.verify() → audit.log()      │
└────────┬────────────────────────────────────────────────────────┘
         │ Device operations (Device Op)
         ▼
┌─────────────────────────────────────────────────────────────────┐
│ L1 Infrastructure                                                │
│   device.write() → scada.scan() → timeseries.write()            │
└─────────────────────────────────────────────────────────────────┘

L5 - Application Layer

The application layer is the topmost layer of EnerOS, carrying specific scenarios for power business. Each application consists of one or more domain Agents, calling kernel capabilities through the Agent runtime.

Responsibilities

• Business process orchestration (dispatch, operations, trading, planning)
• User interaction (CLI, Web, API clients)
• Reports and visualization
• Third-party system integration

Application Components

Application Layer Code Example

use eneros_agent::dispatch_agent::DispatchAgent;
use eneros_core::Command;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create dispatch Agent
    let mut agent = DispatchAgent::builder()
        .with_name("dispatch-001")
        .with_region("east-grid")
        .build()
        .await?;

    // Execute economic dispatch
    let plan = agent.run_economic_dispatch().await?;
    println!("Dispatch plan: {} generators participating", plan.generators.len());

    // Dispatch control commands through safety gateway
    for gen in &plan.generators {
        let cmd = Command::new_generator_setpoint(
            gen.id,
            gen.target_mw,
            "dispatch-001",
        );
        agent.gateway().execute_command(cmd).await?;
    }

    Ok(())
}

L4 - Agent Runtime

The Agent runtime provides complete lifecycle management for Agents, multi-agent collaboration, reasoning, and learning capabilities.

Responsibilities

• Agent lifecycle (creation, suspension, resumption, destruction, migration)
• Multi-agent collaboration (Orchestrator orchestration)
• Memory system (short-term/long-term/vector memory)
• Tool engine (tool registration, invocation, permissions)
• Reasoning engine (LLM integration, ReAct/CoT strategies)
• Learning and reflection (RL, reflection, explanation)

Component Details

Agent Runtime Code Example

use eneros_agent::{Agent, AgentBuilder, Orchestrator};
use eneros_memory::MemoryStore;
use eneros_tool::ToolRegistry;
use eneros_reasoning::ReasoningEngine;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Build memory system
    let memory = MemoryStore::builder()
        .short_term_capacity(100)
        .long_term_path("./data/memory")?
        .build();

    // 2. Build tool engine
    let mut tools = ToolRegistry::new();
    tools.register(Box::new(eneros_tool::builtin::TopologyTool::new()));
    tools.register(Box::new(eneros_tool::builtin::PowerflowTool::new()));
    tools.register(Box::new(eneros_tool::builtin::ConstraintTool::new()));

    // 3. Build reasoning engine
    let reasoning = ReasoningEngine::builder()
        .strategy(eneros_reasoning::Strategy::ReAct)
        .max_iterations(10)
        .build();

    // 4. Build Agent
    let mut agent = AgentBuilder::new()
        .name("grid-assistant")
        .memory(memory)
        .tools(tools)
        .reasoning(reasoning)
        .build()
        .await?;

    // 5. Execute task
    let result = agent
        .run("Analyze current grid topology, find voltage violation nodes")
        .await?;

    println!("Analysis result: {}", result.answer);

    // 6. Multi-Agent collaboration
    let orchestrator = Orchestrator::new();
    orchestrator.register_agent(agent);
    orchestrator.register_agent(DispatchAgent::new().await?);
    orchestrator.register_agent(OperationAgent::new().await?);

    let plan = orchestrator
        .coordinate("Handle grid voltage violation issue")
        .await?;

    Ok(())
}

L3 - Power-Native Kernel

The Power-Native Kernel is the core of EnerOS, building power system domain knowledge, physical constraints, and operational logic as first-class kernel citizens.

Responsibilities

• Grid topology modeling and analysis
• Power flow calculation and state estimation
• Safety constraint validation and projection
• Equipment model library
• Time-series data storage
• Advanced analysis (OPF, short circuit, DSA)
• Event bus and publish-subscribe

Kernel Components

Kernel Code Example

use eneros_topology::{TopologyEngine, Bus, Branch, Switch};
use eneros_powerflow::PowerflowSolver;
use eneros_constraint::{ConstraintEngine, Constraint, ConstraintKind};
use eneros_timeseries::{TimeseriesEngine, Point};

fn main() -> anyhow::Result<()> {
    // 1. Build grid topology
    let mut topo = TopologyEngine::new();
    topo.add_bus(Bus::new(1, "Bus-1", 138.0));
    topo.add_bus(Bus::new(2, "Bus-2", 138.0));
    topo.add_bus(Bus::new(3, "Bus-3", 138.0));
    topo.add_branch(Branch::new(1, 1, 2, 0.01, 0.05));
    topo.add_branch(Branch::new(2, 2, 3, 0.02, 0.08));
    topo.add_switch(Switch::new(1, 3, 1, true));

    // 2. Topology analysis
    let islands = topo.find_islands()?;
    println!("Electrical island count: {}", islands.len());
    let paths = topo.shortest_path(1, 3)?;
    println!("Path from Bus-1 to Bus-3: {:?}", paths);

    // 3. Power flow calculation
    let mut solver = PowerflowSolver::new(topo.graph());
    let result = solver.solve_newton_raphson()?;
    println!("Converged: {} iterations", result.iterations);
    for bus in &result.buses {
        println!("Bus {}: V={:.4}pu, θ={:.2}°", bus.id, bus.voltage, bus.angle);
    }

    // 4. Constraint validation
    let mut constraints = ConstraintEngine::new();
    constraints.add_constraint(Constraint::new(
        ConstraintKind::VoltageLimit,
        "V_min".to_string(),
        0.95,
        1.05,
    ));
    constraints.add_constraint(Constraint::new(
        ConstraintKind::ThermalLimit,
        "Line-1".to_string(),
        0.0,
        100.0,
    ));
    let violations = constraints.check(&result)?;
    for v in &violations {
        println!("Constraint violated: {} = {:.4}", v.constraint_id, v.value);
    }

    // 5. Time-series data write
    let mut ts = TimeseriesEngine::open("./data/ts")?;
    ts.write_point(Point::new(
        "bus-1-voltage",
        chrono::Utc::now(),
        result.buses[0].voltage,
    ))?;

    Ok(())
}

L2 - Real-Time Safety Gateway

The real-time safety gateway is the bridge between the two execution domains, ensuring all cross-domain commands pass safety validation, and providing zero-trust, intrusion detection, audit, and compliance capabilities.

Responsibilities

• Command interception and safety validation
• Zero-trust mTLS communication
• Intrusion detection (behavior baseline + IOC)
• Audit log (HMAC signature + WORM storage)
• Compliance checks (NERC CIP / IEC 62443 / GDPR / PIPL)
• Priority sorting and feasibility projection

Gateway Components

Safety Gateway Code Example

use eneros_gateway::SafetyGateway;
use eneros_trust::{MtlsConfig, CertManager};
use eneros_audit::AuditLogger;
use eneros_ids::IntrusionDetector;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Initialize zero-trust mTLS
    let cert_manager = CertManager::builder()
        .ca_cert_path("./certs/ca.pem")
        .server_cert_path("./certs/server.pem")
        .server_key_path("./certs/server.key")
        .build()?;
    let mtls = MtlsConfig::from_cert_manager(&cert_manager)?;

    // 2. Initialize audit log (HMAC + WORM)
    let audit = AuditLogger::builder()
        .storage_path("./audit")
        .hmac_key(b"audit-secret-key-32-bytes-long!")
        .worm_enabled(true)
        .build()?;

    // 3. Initialize intrusion detection
    let ids = IntrusionDetector::builder()
        .baseline_window(chrono::Duration::hours(24))
        .alert_threshold(0.8)
        .build()?;

    // 4. Build safety gateway
    let gateway = SafetyGateway::new(10000)
        .with_lockfree_state();

    // 5. Register safety checks
    gateway.register_safety_check(Box::new(audit.clone()));
    gateway.register_safety_check(Box::new(ids.clone()));

    // 6. Execute command (automatic audit + intrusion detection)
    let cmd = eneros_core::Command::new_switch_toggle(42, false, "operator-1");
    gateway.execute_command(cmd).await?;

    // 7. Query audit history
    let history = gateway.command_history();
    println!("Audit record count: {}", history.len());

    Ok(())
}

L1 - Infrastructure

The infrastructure layer provides operating system services, network, storage, multi-region, multi-tenant, protocol adaptation, and device management capabilities.

Responsibilities

• OS services (init / rt / agentos / hal)
• Network configuration and firewall
• Multi-region replication and disaster recovery
• Multi-tenant isolation and quotas
• SCADA data acquisition
• Device protocol adaptation (IEC 104 / Modbus / DNP3 / PMU / MQTT)
• Performance optimization (arena / pool / ring buffer)

Infrastructure Components

Protocol Adaptation

Infrastructure Code Example

use eneros_os::rt::{RtConfig, RtRuntime};
use eneros_multiregion::{MultiRegionManager, RegionConfig};
use eneros_tenant::{TenantManager, TenantConfig};
use eneros_scada::{ScadaCollector, ProtocolType};
use eneros_device::{DeviceManager, ProtocolConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Configure real-time runtime
    let rt_config = RtConfig {
        cpus: vec![2, 3],
        priority: 80,
        lock_memory: true,
        use_huge_pages: true,
    };
    let rt = RtRuntime::new(rt_config);
    rt.configure_current_thread()?;

    // 2. Multi-region replication
    let region = MultiRegionManager::new(RegionConfig {
        local_region: "east-1".to_string(),
        peer_regions: vec!["west-1".to_string(), "north-1".to_string()],
        replication_mode: eneros_multiregion::ReplicationMode::AsyncWal,
    });

    // 3. Multi-tenant isolation
    let tenants = TenantManager::new(TenantConfig {
        default_quota: eneros_tenant::Quota {
            max_agents: 100,
            max_storage_gb: 100,
            max_requests_per_sec: 1000,
        },
    });
    tenants.create_tenant("tenant-001", "Power Company A").await?;

    // 4. SCADA data acquisition
    let mut scada = ScadaCollector::new();
    scada.add_channel("rtu-1", ProtocolType::Iec104, "192.168.1.10:2404")?;
    scada.add_channel("rtu-2", ProtocolType::Cdt, "192.168.1.11:2404")?;
    scada.start().await?;

    // 5. Device management
    let devices = DeviceManager::new();
    devices
        .register_device(
            "rtu-1",
            Box::new(eneros_device::adapter::ModbusAdapter::new()),
            eneros_device::adapter::ConnectionConfig {
                host: "192.168.1.10".into(),
                port: 502,
                timeout_ms: 3000,
                credentials: None,
                protocol_config: ProtocolConfig::Modbus {
                    slave_id: 1,
                    baud_rate: None,
                },
            },
            eneros_device::adapter::DeviceInfo {
                device_id: "rtu-1".into(),
                name: "RTU-1".into(),
                protocol: eneros_device::protocol::ProtocolType::Modbus,
                manufacturer: "Siemens".into(),
                model: "S7-1500".into(),
                firmware_version: "1.0.0".into(),
                ip_address: "192.168.1.10".into(),
                port: 502,
                capabilities: vec!["read".into(), "write".into()],
            },
        )
        .await;

    Ok(())
}

Inter-Layer Interface Specification

L5 → L4: Agent SDK

The application layer calls runtime capabilities through the Agent SDK, with interface form being Rust trait + async methods:

// Interface exposed by L4 to L5
pub trait AgentRuntime: Send + Sync {
    async fn create_agent(&self, config: AgentConfig) -> Result<AgentHandle>;
    async fn invoke_agent(&self, handle: &AgentHandle, input: AgentInput) -> Result<AgentOutput>;
    async fn destroy_agent(&self, handle: AgentHandle) -> Result<()>;
}

L4 → L3: Kernel System Calls

The Agent runtime accesses power-native capabilities through kernel system calls:

// Interface exposed by L3 to L4
pub trait PowerNativeKernel: Send + Sync {
    fn topology(&self) -> &dyn TopologyApi;
    fn powerflow(&self) -> &dyn PowerflowApi;
    fn constraint(&self) -> &dyn ConstraintApi;
    fn timeseries(&self) -> &dyn TimeseriesApi;
    fn eventbus(&self) -> &dyn EventBusApi;
}

pub trait TopologyApi: Send + Sync {
    fn find_islands(&self) -> Result<Vec<Vec<BusId>>>;
    fn shortest_path(&self, from: BusId, to: BusId) -> Result<Vec<BusId>>;
}

L3 → L2: Command Dispatch

The kernel dispatches control instructions to the safety gateway through command objects:

// Interface exposed by L2 to L3
pub trait SafetyGatewayApi: Send + Sync {
    async fn execute_command(&self, cmd: Command) -> Result<ExecutionResult>;
    async fn validate_command(&self, cmd: &Command) -> Result<()>;
    fn command_history(&self) -> Vec<Command>;
}

L2 → L1: Device Operations

The safety gateway accesses physical devices through the device manager:

// Interface exposed by L1 to L2
pub trait DeviceManagerApi: Send + Sync {
    async fn read(&self, device_id: &str, address: &str) -> Result<DataValue>;
    async fn write(&self, device_id: &str, address: &str, value: DataValue) -> Result<()>;
    async fn connect(&self, device_id: &str) -> Result<()>;
    async fn disconnect(&self, device_id: &str) -> Result<()>;
}

Complete Component Reference Table by Layer

Related Documentation

• Dual-Execution Architecture - Dual execution domain details
• Crate Dependencies - Crate dependency graph