Project Structure

The EnerOS repository uses a Cargo workspace to organize 56 Rust crates, following the module organization principles of “separation of concerns, single responsibility, minimal dependencies.” The repository root contains top-level directories such as crates/, os/, docs/, examples/, tests/, tools/, scripts/.

Complete Directory Tree

eneros/
├── crates/                       # 56 Rust crates (libraries + binaries)
│   ├── eneros-core/              # L0 core types and errors
│   ├── eneros-linalg/            # L0 sparse linear algebra
│   ├── eneros-perf/              # L1 performance optimization (arena/pool/ring)
│   ├── eneros-audit/             # L2 audit log (HMAC + WORM)
│   ├── eneros-topology/          # L3 grid topology engine
│   ├── eneros-powerflow/         # L3 power flow calculation
│   ├── eneros-constraint/        # L3 safety constraint engine
│   ├── eneros-equipment/         # L3 equipment model library
│   ├── eneros-cnpower/           # L3 Chinese distribution equipment and standards
│   ├── eneros-timeseries/        # L3 time-series storage
│   ├── eneros-eventbus/          # L3 event bus
│   │   └── bins/broker/          # Event broker binary
│   ├── eneros-gateway/           # L2 safety gateway
│   │   └── bins/gateway/         # Gateway binary
│   ├── eneros-device/            # L1 device management and protocol adaptation
│   ├── eneros-api/               # L1 REST/GraphQL/SSE API
│   ├── eneros-runtime/           # L1 top-level runtime composition
│   ├── eneros-bridge/            # L3 external system bridging
│   ├── eneros-network/           # L3 CIM network model
│   ├── eneros-memory/            # L4 memory system
│   ├── eneros-tenant/            # L1 multi-tenant isolation
│   ├── eneros-tool/              # L4 tool engine
│   ├── eneros-reasoning/         # L4 reasoning engine
│   ├── eneros-agent/             # L4 Agent runtime
│   │   └── bins/                 # Agent binaries
│   │       ├── dispatch-agent/   # Intelligent dispatch Agent
│   │       ├── forecast-agent/   # Load forecasting Agent
│   │       ├── operation-agent/  # Intelligent operations Agent
│   │       ├── self-healing-agent/ # Fault self-healing Agent
│   │       ├── planning-agent/   # Distribution planning Agent
│   │       └── trading-agent/    # Electricity trading Agent
│   ├── eneros-test-utils/        # L1 test utilities
│   ├── eneros-scada/             # L1 SCADA data acquisition
│   ├── eneros-twin/              # L4 digital twin
│   ├── eneros-graphql/           # L1 GraphQL schema
│   ├── eneros-ai/                # L4 AI/ML integration
│   ├── eneros-aiops/             # L4 AIOps
│   ├── eneros-edge/              # L5 edge intelligence
│   ├── eneros-protocol-iec103/   # L1 IEC 103 protocol
│   ├── eneros-protocol-cdt/      # L1 CDT protocol
│   ├── eneros-protocol-pmu/      # L1 PMU protocol
│   ├── eneros-protocol-iccp/     # L1 ICCP protocol
│   ├── eneros-protocol-mqtt/     # L1 MQTT protocol
│   ├── eneros-protocol-coap/     # L1 CoAP protocol
│   ├── eneros-protocol-lwm2m/    # L1 LwM2M protocol
│   ├── eneros-protocol-dlt698/   # L1 DLT 698 protocol
│   ├── eneros-analysis/          # L3 advanced analysis
│   ├── eneros-dashboard/         # L5 web visualization
│   ├── eneros-simulator/         # L3 scenario simulator
│   ├── eneros-slo/               # L1 SLO/SLI evaluation
│   ├── eneros-plugin/            # L1 plugin system
│   │   └── bins/plugin-daemon/   # Plugin daemon
│   ├── eneros-plugin-macros/     # L1 plugin derive macros
│   ├── eneros-sdk/               # L1 multi-language SDK
│   │   └── bindings/
│   │       ├── c/                # C bindings
│   │       └── python/           # Python bindings
│   ├── eneros-ops/               # L1 operations automation
│   ├── eneros-os/                # L1 OS services
│   │   └── bins/
│   │       ├── eneros-init/      # System initialization
│   │       ├── eneros-ha/        # High availability daemon
│   │       ├── eneros-timesync/  # Time synchronization
│   │       ├── enerosctl/        # Management CLI
│   │       ├── eneros-installer/ # Installer
│   │       ├── eneros-autoscaler/ # Auto-scaling
│   │       ├── eneros-backup/    # Backup tool
│   │       ├── eneros-oncall/    # On-call management
│   │       ├── eneros-dr-orchestrator/ # Disaster recovery orchestration
│   │       └── eneros-upgrader/  # OTA upgrader
│   ├── eneros-market/            # L5 electricity market
│   │   └── bins/market-server/   # Market server
│   ├── eneros-ids/               # L2 intrusion detection
│   ├── eneros-compliance/        # L2 compliance checks
│   ├── eneros-trust/             # L2 zero-trust mTLS
│   ├── eneros-multiregion/       # L1 multi-region replication
│   ├── eneros-emtp/              # L3 electromagnetic transient simulation
│   ├── eneros-iot-hub/           # L1 IoT access hub
│   ├── eneros-nl/                # L5 natural language interaction
│   ├── eneros-3d/                # L3 3D visualization scenes
│   ├── eneros-report/            # L5 report generation
│   └── eneros-i18n/              # L1 internationalization
├── os/                           # OS layer (system-level services and images)
│   ├── boot/                     # Boot configuration
│   │   ├── grub.cfg              # GRUB configuration
│   │   ├── secure-boot.sh        # Secure boot script
│   │   ├── build-initramfs.sh    # Build initramfs
│   │   └── systemd-boot.conf     # systemd-boot configuration
│   ├── kernel/                   # Kernel configuration and patches
│   │   ├── patches/              # Kernel patches
│   │   ├── config-x86_64         # x86_64 kernel config
│   │   ├── config-aarch64        # aarch64 kernel config
│   │   └── build.sh              # Kernel build script
│   ├── rootfs/                   # Root filesystem
│   │   ├── files/
│   │   │   └── etc/eneros/       # EnerOS configuration files
│   │   │       ├── init.toml     # Initialization config
│   │   │       ├── ha.toml       # High availability config
│   │   │       ├── audit.toml    # Audit config
│   │   │       ├── network.toml  # Network config
│   │   │       ├── plugin.toml   # Plugin config
│   │   │       └── syslog.toml   # System log config
│   │   └── build.sh              # rootfs build script
│   ├── image-builder/            # System image building
│   │   ├── build.sh              # Image build script
│   │   ├── create-partitions.sh  # Partition creation
│   │   ├── inject-config.sh      # Config injection
│   │   └── install-bootloader.sh # Bootloader installation
│   └── tests/                    # OS boot tests
│       ├── boot_test.rs          # Boot test
│       └── boot_params_test.rs   # Boot parameters test
├── docs/                         # Project documentation
│   ├── adr/                      # Architecture Decision Records
│   │   ├── 0002-power-native-agentos.md
│   │   ├── 0007-zero-trust-mtls.md
│   │   ├── 0008-ops-automation.md
│   │   ├── 0009-ha-enhancement.md
│   │   ├── 0010-agent-intelligence.md
│   │   ├── 0012-iot-ubiquitous-access.md
│   │   ├── 0013-visualization-stack.md
│   │   └── 0014-i18n-compliance.md
│   ├── compliance/               # Compliance documentation
│   │   ├── gdpr-pipl-ccpa.md     # Data protection compliance
│   │   ├── iec-62443-4-1-sdlc.md # IEC 62443 SDLC
│   │   ├── nerc-cip-005.md       # NERC CIP-005
│   │   ├── nerc-cip-007.md       # NERC CIP-007
│   │   └── nerc-cip-010.md       # NERC CIP-010
│   ├── deployment.md             # Deployment documentation
│   ├── developer-guide.md        # Developer guide
│   ├── plugin-development.md     # Plugin development guide
│   └── user-manual.md            # User manual
├── locales/                      # Internationalization resources
│   ├── en-US.ftl                 # English
│   ├── zh-CN.ftl                 # Simplified Chinese
│   ├── ja-JP.ftl                 # Japanese
│   └── es-ES.ftl                 # Spanish
├── tests/                        # Integration tests
│   ├── e2e/                      # End-to-end tests
│   │   ├── scenarios/            # Test scenarios
│   │   │   ├── ha_failover.rs    # High availability failover
│   │   │   └── startup.rs        # Startup test
│   │   └── tests/e2e_tests.rs    # E2E test entry
│   ├── protocol_conformance/     # Protocol conformance tests
│   ├── security/                 # Security tests
│   │   ├── owasp/                # OWASP Top 10
│   │   └── tests/security_tests.rs
├── benches/                      # Performance benchmarks
│   ├── benches/
│   │   ├── agent_bench.rs        # Agent performance
│   │   ├── ai_bench.rs           # AI inference performance
│   │   ├── api_bench.rs          # API performance
│   │   ├── grid_analysis_bench.rs # Grid analysis performance
│   │   ├── ha_bench.rs           # High availability performance
│   │   ├── iot_bench.rs          # IoT performance
│   │   ├── perf_bench.rs         # General performance
│   │   ├── powerflow_bench.rs    # Power flow calculation performance
│   │   ├── scada_bench.rs        # SCADA performance
│   │   ├── twin_bench.rs         # Digital twin performance
│   │   └── visualization_bench.rs # Visualization performance
│   └── baseline.json             # Performance baseline
├── templates/                    # Code templates
│   └── plugin-ci-cd/             # Plugin CI/CD template
├── deploy/                       # Deployment configuration
│   ├── docker/
│   │   ├── Dockerfile            # Container image
│   │   └── docker-compose.yml    # Orchestration config
│   ├── scripts/
│   │   ├── build.sh              # Build script
│   │   ├── dev.sh                # Development script
│   │   └── healthcheck.sh        # Health check
│   └── prometheus.yml            # Prometheus monitoring config
├── third_party/                  # Third-party dependencies
│   ├── cnpower/                  # Chinese distribution reference library
│   └── pandapower/               # pandapower reference library
├── .github/                      # GitHub configuration
│   └── workflows/                # CI/CD pipelines
│       ├── ci.yml                # Continuous integration
│       ├── e2e.yml               # End-to-end testing
│       ├── security.yml          # Security scanning
│       ├── benchmark.yml         # Performance benchmarks
│       ├── coverage.yml          # Coverage
│       ├── conformance.yml       # Protocol conformance
│       ├── release.yml           # Release pipeline
│       └── deploy-web.yml        # Documentation site deployment
├── Cargo.toml                    # Workspace configuration
├── Cargo.lock                    # Dependency lock
├── deny.toml                     # cargo-deny configuration
├── eneros.toml                   # Runtime default configuration
├── README.md                     # Project description (Chinese)
├── README_en.md                  # Project description (English)
├── CHANGELOG.md                  # Change log
├── ROADMAP.md                    # Roadmap
└── CONTRIBUTING.md               # Contribution guidelines

Top-Level Directory Description

Directory	Purpose	Pushed to GitHub	Description
`crates/`	56 Rust crates	✅	Libraries + binaries, can be depended on by other projects
`os/`	OS system layer	✅	Boot, kernel config, rootfs, image building
`docs/`	Project documentation	✅	ADR, compliance, deployment, development guides
`locales/`	Internationalization resources	✅	Fluent translation files (.ftl)
`tests/`	Integration tests	✅	E2E, protocol conformance, security tests
`benches/`	Performance benchmarks	✅	criterion benchmark tests
`templates/`	Code templates	✅	Plugin CI/CD and other templates
`deploy/`	Deployment configuration	✅	Docker, scripts, monitoring
`third_party/`	Third-party reference libraries	✅	cnpower, pandapower submodules
`.github/`	CI/CD configuration	✅	GitHub Actions workflows
`.trae/`	AI development files	❌	Local spec/rules, not uploaded
`DEVGUIDE.md`	AI development manual	❌	Local architecture map, gitignore
`target/`	Build artifacts	❌	cargo build cache

crates/ vs os/

Directory	Purpose	Build Artifacts	Examples
`crates/`	Rust library crates (dependable)	.rlib / .so / .exe	eneros-core, eneros-powerflow
`crates/*/bins/`	Rust binary crates	Executables	dispatch-agent, enerosctl
`os/`	OS system layer (non-Rust)	Config/scripts/images	grub.cfg, rootfs, kernel config

Cargo Workspace Configuration

Core Configuration

# Cargo.toml (workspace root)
[workspace]
resolver = "2"
members = [
    "crates/eneros-core",
    "crates/eneros-linalg",
    "crates/eneros-perf",
    "crates/eneros-audit",
    "crates/eneros-topology",
    "crates/eneros-powerflow",
    "crates/eneros-constraint",
    "crates/eneros-equipment",
    "crates/eneros-cnpower",
    "crates/eneros-timeseries",
    "crates/eneros-eventbus",
    "crates/eneros-eventbus/bins/broker",
    "crates/eneros-gateway",
    "crates/eneros-gateway/bins/gateway",
    "crates/eneros-device",
    "crates/eneros-api",
    "crates/eneros-runtime",
    "crates/eneros-bridge",
    "crates/eneros-network",
    "crates/eneros-memory",
    "crates/eneros-tenant",
    "crates/eneros-tool",
    "crates/eneros-reasoning",
    "crates/eneros-agent",
    "crates/eneros-agent/bins/dispatch-agent",
    "crates/eneros-agent/bins/forecast-agent",
    "crates/eneros-agent/bins/operation-agent",
    "crates/eneros-agent/bins/self-healing-agent",
    "crates/eneros-agent/bins/planning-agent",
    "crates/eneros-agent/bins/trading-agent",
    "crates/eneros-test-utils",
    "crates/eneros-scada",
    "crates/eneros-twin",
    "crates/eneros-graphql",
    "crates/eneros-ai",
    "crates/eneros-aiops",
    "crates/eneros-edge",
    "crates/eneros-protocol-iec103",
    "crates/eneros-protocol-cdt",
    "crates/eneros-protocol-pmu",
    "crates/eneros-protocol-iccp",
    "crates/eneros-analysis",
    "crates/eneros-dashboard",
    "crates/eneros-simulator",
    "crates/eneros-slo",
    "crates/eneros-plugin",
    "crates/eneros-plugin/bins/plugin-daemon",
    "crates/eneros-plugin-macros",
    "crates/eneros-sdk",
    "crates/eneros-sdk/bindings/c",
    "crates/eneros-sdk/bindings/python",
    "crates/eneros-ops",
    "crates/eneros-os",
    "crates/eneros-os/bins/eneros-init",
    "crates/eneros-os/bins/eneros-ha",
    "crates/eneros-os/bins/eneros-timesync",
    "crates/eneros-os/bins/enerosctl",
    "crates/eneros-os/bins/eneros-installer",
    "crates/eneros-os/bins/eneros-autoscaler",
    "crates/eneros-os/bins/eneros-backup",
    "crates/eneros-os/bins/eneros-oncall",
    "crates/eneros-os/bins/eneros-dr-orchestrator",
    "crates/eneros-os/bins/eneros-upgrader",
    "crates/eneros-market",
    "crates/eneros-market/bins/market-server",
    "crates/eneros-ids",
    "crates/eneros-compliance",
    "crates/eneros-trust",
    "crates/eneros-multiregion",
    "crates/eneros-emtp",
    "crates/eneros-protocol-mqtt",
    "crates/eneros-protocol-coap",
    "crates/eneros-protocol-lwm2m",
    "crates/eneros-protocol-dlt698",
    "crates/eneros-iot-hub",
    "crates/eneros-nl",
    "crates/eneros-3d",
    "crates/eneros-report",
    "crates/eneros-i18n",
    "os/tests",
    "tests/e2e",
    "tests/protocol_conformance",
    "tests/security",
    "benches",
]

[workspace.package]
version = "0.44.0"
edition = "2021"
authors = ["GAWG-AI"]
license = "MIT"
description = "EnerOS - Power-Native Agent Operating System"

[workspace.dependencies]
# Async runtime
tokio = { version = "1", features = ["full"] }
async-trait = "0.1"
futures = "0.3"

# Serialization
serde = { version = "1", features = ["derive"] }
serde_json = "1"
bincode = "1"

# Logging and tracing
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["json", "env-filter"] }

# Error handling
thiserror = "1"
anyhow = "1"

# Data structures
dashmap = "5"
parking_lot = "0.12"
uuid = { version = "1", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }

# Math and scientific computing
ndarray = { version = "0.15", features = ["serde"] }
num-complex = { version = "0.4", features = ["serde"] }
sprs = "0.11"

# Security
jsonwebtoken = "9"
sha2 = "0.10"
hmac = "0.12"
aes-gcm = "0.10"
ed25519-dalek = { version = "2", features = ["rand_core"] }
zeroize = { version = "1", features = ["derive", "serde", "alloc"] }
libseccomp = "0.4"

# TLS
tokio-rustls = "0.26"
rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }

# Internal crates (path dependencies)
eneros-core = { path = "crates/eneros-core" }
eneros-linalg = { path = "crates/eneros-linalg" }
# ... other internal crates declared as path dependencies

Single Crate Cargo.toml Example

# crates/eneros-powerflow/Cargo.toml
[package]
name = "eneros-powerflow"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
description = "EnerOS power flow solver (Newton-Raphson)"

[dependencies]
# EnerOS internal dependencies
eneros-core = { workspace = true }
eneros-linalg = { workspace = true }
eneros-topology = { workspace = true }

# Third-party dependencies
tokio = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
tracing = { workspace = true }
thiserror = { workspace = true }
ndarray = { workspace = true }
sprs = { workspace = true }

[dev-dependencies]
eneros-test-utils = { workspace = true }
criterion = { workspace = true }

[[bench]]
name = "powerflow_bench"
harness = false

Key File Descriptions

Root Directory Files

File	Purpose	Sync Trigger
`Cargo.toml`	Workspace config (members + dependencies)	Adding/removing crates
`Cargo.lock`	Dependency version lock	Auto-updated by cargo build
`deny.toml`	cargo-deny config (licenses/duplicate deps)	Dependency changes
`eneros.toml`	Runtime default configuration	Configuration changes
`README.md`	Project description (Chinese)	Version/feature/architecture changes
`README_en.md`	Project description (English)	Sync with README.md
`CHANGELOG.md`	Change log	Each code change
`ROADMAP.md`	Roadmap	Updated at version releases
`CONTRIBUTING.md`	Contribution guidelines	When processes change

OS Layer Configuration Files

File	Path	Purpose
`init.toml`	`os/rootfs/files/etc/eneros/`	System initialization config
`ha.toml`	`os/rootfs/files/etc/eneros/`	High availability config
`audit.toml`	`os/rootfs/files/etc/eneros/`	Audit config
`network.toml`	`os/rootfs/files/etc/eneros/`	Network config
`plugin.toml`	`os/rootfs/files/etc/eneros/`	Plugin config
`syslog.toml`	`os/rootfs/files/etc/eneros/`	System log config
`grub.cfg`	`os/boot/`	GRUB boot configuration
`config-x86_64`	`os/kernel/`	x86_64 kernel config
`config-aarch64`	`os/kernel/`	aarch64 kernel config

eneros.toml Runtime Configuration

# eneros.toml - Runtime default configuration
[server]
host = "0.0.0.0"
port = 8080
workers = 4

[realtime]
cpus = [2, 3]
priority = 80
lock_memory = true
use_huge_pages = true

[database]
path = "./data/eneros.db"
timeseries_path = "./data/ts"

[security]
mtls_enabled = true
ca_cert_path = "./certs/ca.pem"
server_cert_path = "./certs/server.pem"
server_key_path = "./certs/server.key"

[audit]
storage_path = "./audit"
hmac_key = "change-me-in-production-32-bytes"
worm_enabled = true

[ha]
enabled = false
peers = []
heartbeat_interval_ms = 1000
failover_timeout_ms = 5000

[multiregion]
local_region = "default"
peer_regions = []
replication_mode = "async_wal"

Module Organization Principles

1. Single Responsibility

Each crate is responsible for only one clear responsibility:

// ✅ Correct: eneros-topology only handles topology
crate eneros-topology {
    mod graph;      // Graph data structure
    mod engine;     // Topology engine
    mod search;     // Search algorithms
}

// ❌ Wrong: mixing power flow into eneros-topology
crate eneros-topology {
    mod graph;
    mod powerflow;  // Should be in eneros-powerflow
}

2. Interface and Implementation Separation

Expose interfaces through traits, hide implementations in impl modules:

// crates/eneros-powerflow/src/lib.rs
pub mod solver;      // Expose PowerflowSolver trait
pub mod result;      // Expose PowerflowResult type
mod matrix;          // Internal matrix utilities (not exposed)
mod ieee;            // Internal IEEE standard implementation (not exposed)

// Public API
pub use solver::{PowerflowSolver, NewtonRaphsonSolver};
pub use result::PowerflowResult;

3. Test Organization

Test Type	Location	Naming	Run Command
Unit tests	`src/*.rs` in `#[cfg(test)] mod tests`	`test_*`	`cargo test -p <crate>`
Integration tests	`tests/*.rs`	`*_test.rs`	`cargo test --test <name>`
End-to-end tests	`tests/e2e/`	`e2e_*.rs`	`cargo test --package e2e`
Protocol conformance	`tests/protocol_conformance/`	—	`cargo test --package protocol_conformance`
Security tests	`tests/security/`	—	`cargo test --package security`
OS boot tests	`os/tests/`	`*_test.rs`	`cargo test --package os-tests`
Performance benchmarks	`benches/benches/`	`*_bench.rs`	`cargo bench`

4. Module Naming Conventions

Naming Object	Convention	Example
Crate	`eneros-<domain>`	`eneros-topology`, `eneros-powerflow`
Binary	`eneros-<service>` or `<domain>-agent`	`enerosctl`, `dispatch-agent`
Module	`<domain>` or `<feature>`	`topology`, `powerflow`, `gateway`
Trait	PascalCase, noun	`TopologyEngine`, `SafetyGateway`
Function	snake_case, verb prefix	`find_islands`, `solve_powerflow`
Type	PascalCase, noun	`Bus`, `Branch`, `Command`
Constant	SCREAMING_SNAKE_CASE	`MAX_HISTORY`, `SHM_MAGIC`

Code Organization Standards

Directory Structure Standards

Each crate follows a unified directory structure:

crates/eneros-<name>/
├── Cargo.toml          # crate configuration
├── README.md           # crate description (optional)
├── src/
│   ├── lib.rs          # Library entry (public API)
│   ├── error.rs        # Error types
│   ├── types.rs        # Core types
│   ├── <module>.rs     # Business modules
│   └── tests/          # Integration tests (optional)
├── tests/
│   └── <test>.rs       # Integration tests
└── benches/
    └── <bench>.rs      # Performance benchmarks (optional)

Binary Crate Structure

crates/eneros-<name>/bins/<binary>/
├── Cargo.toml          # Binary configuration
└── src/
    └── main.rs         # Entry point

Example: eneros-os Crate Structure

crates/eneros-os/
├── Cargo.toml
├── src/
│   ├── lib.rs              # Public API entry
│   ├── init/               # System initialization
│   │   ├── mod.rs
│   │   ├── manager.rs      # init manager
│   │   ├── config.rs       # Config loading
│   │   ├── service.rs      # Service management
│   │   └── supervisor.rs   # Process supervision
│   ├── rt/                 # Real-time runtime
│   │   ├── mod.rs
│   │   ├── runtime.rs      # RtRuntime
│   │   ├── ipc.rs          # Lock-free SPSC queue
│   │   ├── shm.rs          # Shared memory channel
│   │   └── watchdog.rs     # Watchdog
│   ├── agentos/            # Agent OS services
│   │   ├── mod.rs
│   │   ├── ipc.rs          # Agent IPC
│   │   ├── quota.rs        # Resource quotas
│   │   └── seccomp.rs      # seccomp sandbox
│   ├── ha/                 # High availability
│   │   ├── mod.rs
│   │   ├── cluster.rs      # Cluster management
│   │   ├── failover.rs     # Failover
│   │   ├── fencing.rs      # Split-brain protection
│   │   ├── heartbeat.rs    # Heartbeat detection
│   │   └── replication.rs  # State replication
│   ├── hal/                # Hardware abstraction layer
│   │   ├── mod.rs
│   │   ├── linux_hal.rs    # Linux HAL
│   │   └── sensor.rs       # Sensor interface
│   ├── netcfg/             # Network configuration
│   ├── syslog/             # System logging
│   │   ├── mod.rs
│   │   └── rotate.rs       # Log rotation
│   ├── timesync/           # Time synchronization
│   │   ├── mod.rs
│   │   ├── ntp.rs          # NTP client
│   │   └── ptp.rs          # PTP (Precision Time Protocol)
│   ├── security/           # Security module
│   ├── devmgr/             # Device management
│   │   ├── mod.rs
│   │   └── hotplug.rs      # Hot-plug
│   └── update/             # OTA upgrade
│       ├── mod.rs
│       ├── ota.rs          # OTA main logic
│       ├── manifest.rs     # Upgrade manifest
│       └── signer.rs       # Signature verification
├── tests/
│   └── init_test.rs        # Initialization test
└── bins/                   # Binaries
    ├── eneros-init/        # System initialization daemon
    ├── eneros-ha/          # High availability daemon
    ├── eneros-timesync/    # Time synchronization daemon
    ├── enerosctl/          # Management CLI
    ├── eneros-installer/   # Installer
    ├── eneros-autoscaler/  # Auto-scaling
    ├── eneros-backup/      # Backup tool
    ├── eneros-oncall/      # On-call management
    ├── eneros-dr-orchestrator/ # Disaster recovery orchestration
    └── eneros-upgrader/    # OTA upgrader

Build and Testing

Build Commands

# Build all crates
cargo build --release

# Build specific crate
cargo build -p eneros-powerflow

# Build specific binary
cargo build -p enerosctl

# Build eneros-init (with OS features)
cargo build -p eneros-init --features os

# Build WORM audit (with audit features)
cargo build -p eneros-audit --features worm

Test Commands

# Run all tests
cargo test

# Run specific crate tests
cargo test -p eneros-powerflow

# Run end-to-end tests
cargo test --package e2e

# Run security tests
cargo test --package security

# Run protocol conformance tests
cargo test --package protocol_conformance

# Run performance benchmarks
cargo bench

Code Quality

# Code formatting
cargo fmt --all

# Static analysis
cargo clippy --all -- -D warnings

# Dependency audit
cargo deny check

# Duplicate dependency detection
cargo tree -d

# Coverage
cargo tarpaulin --out Html

CI/CD Pipelines

CI/CD configuration is located in .github/workflows/, containing the following pipelines:

Pipeline	File	Trigger	Description
Continuous integration	`ci.yml`	push/PR	Build + unit tests + clippy
End-to-end testing	`e2e.yml`	push to main	E2E tests
Security scanning	`security.yml`	push/PR	SAST + dependency audit
Performance benchmarks	`benchmark.yml`	push to main	Performance regression detection
Coverage	`coverage.yml`	push to main	Code coverage reporting
Protocol conformance	`conformance.yml`	push/PR	Power protocol conformance
Release	`release.yml`	tag	Publish to crates.io + GitHub Release
Documentation site	`deploy-web.yml`	push to main	Deploy docs site to GitHub Pages

Development Workflow

Adding a New Crate

Create a new directory under crates/:

mkdir -p crates/eneros-newfeature/src

Create Cargo.toml:

[package]
name = "eneros-newfeature"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
description = "EnerOS new feature"

[dependencies]
eneros-core = { workspace = true }
# Other dependencies

Create src/lib.rs:

//! EnerOS new feature module

pub mod error;
pub mod types;

pub use error::{NewFeatureError, Result};
pub use types::NewFeature;

Add to root Cargo.toml members:

members = [
    # ...
    "crates/eneros-newfeature",
]

Add path dependency in [workspace.dependencies]:

eneros-newfeature = { path = "crates/eneros-newfeature" }

Sync documentation:
- Update CHANGELOG.md
- Update DEVGUIDE.md (if exists)
- Update docs/developer-guide.md
- Add new docs/adr/000N-*.md if necessary

Development Environment Setup

# 1. Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable

# 2. Install components
rustup component add rustfmt clippy
cargo install cargo-deny cargo-tarpaulin cargo-audit

# 3. Clone repository
git clone https://github.com/Gawg-AI/EnerOS.git
cd EnerOS

# 4. Build verification
cargo build
cargo test
cargo clippy -- -D warnings

Crate Dependencies - Dependency graph
Layered Architecture - Five-layer architecture details
Dual-Execution Architecture - Dual execution domain details
Crate Index - Complete crate list

Project Structure

Project Structure

Complete Directory Tree

Top-Level Directory Description

crates/ vs os/

Cargo Workspace Configuration

Core Configuration

Single Crate Cargo.toml Example

Key File Descriptions

Root Directory Files

OS Layer Configuration Files

eneros.toml Runtime Configuration

Module Organization Principles

1. Single Responsibility

2. Interface and Implementation Separation

3. Test Organization

4. Module Naming Conventions

Code Organization Standards

Directory Structure Standards

Binary Crate Structure

Example: eneros-os Crate Structure

Build and Testing

Build Commands

Test Commands

Code Quality

CI/CD Pipelines

Development Workflow

Adding a New Crate

Development Environment Setup

Related Documentation