Architecture Decision Records (ADR) Overview

Architecture Decision Records (ADR) are used to capture key decisions in the EnerOS project that have a sustained impact on architecture. Each ADR records the context, motivation, conclusion, and consequences of a decision, facilitating team review and helping new members understand the design rationale.

ADR is not a design document, nor an implementation specification; it answers “why this choice was made at that time.” When code cannot explain the decision motivation, ADR is the final basis. EnerOS is an operating system for power critical infrastructure; many decisions are influenced by compliance, physical constraints, and long-term evolution, and must be explicitly recorded. Otherwise, as personnel change, the reasons for decisions will be lost.

Why ADR is Needed

Power system software development has the following characteristics, making ADR especially important:

• Long lifecycle: Power systems typically run for 10-30 years after commissioning, and decision impact far exceeds individual tenure
• Strong compliance constraints: Must simultaneously satisfy multiple standards such as IEC 62443, NERC CIP, and MLPS 2.0
• Physical irreversibility: Incorrect remote commands may cause equipment damage or large-scale outages
• Multi-party collaboration: Grid companies, equipment vendors, regulators, and research institutions all need to understand the system design
• Rapid technology evolution: AI, edge computing, quantum security, and other new technologies continuously impact existing architectures

ADR provides structured recording of decision context, enabling newly joined engineers to understand key questions like “why the kernel must enforce constraints” and “why all internal communication must use mTLS” within 30 minutes, avoiding unconscious overturning of established decisions.

ADR Format

EnerOS adopts the lightweight ADR template proposed by Michael Nygard, extended to a six-section structure. Each ADR must contain the following sections:

State Machine

ADR states follow these transition rules:

Proposed
   │
   ├─ Review approved ──► Accepted
   │                         │
   │                         ├─ Superseded by later ADR ──► Superseded
   │                         ├─ Serious issues exposed ──► Deprecated
   │                         └─ Long-term valid
   │
   └─ Review rejected ──► Rejected

Once the status becomes “Accepted,” the original file content is no longer modified and can only be superseded by a new ADR. This ensures historical traceability—any decision evolution is explicitly recorded through new ADRs.

ADR List

The following table is an index of all current EnerOS ADRs. Numbering starts from 0001, increments chronologically, and is not reused. Missing numbers represent rejected or withdrawn proposals; the numbers are retained as placeholders to maintain temporal integrity.

Note: ADRs numbered 0001, 0003-0006, and 0008-0009 involve internal component selection (such as time-series storage engine, scheduler implementation, event bus protocol, etc.), and the index will be gradually completed after subsequent versions are made public.

ADR Template

When creating a new ADR, copy the following template and fill in the fields:

---
title: "ADR-NNNN Title"
description: "One-sentence description of the decision"
category: "Architecture Decision Records"
order: NNNN
---

# ADR-NNNN Title

- **Status**: Proposed | Accepted | Deprecated | Superseded
- **Date**: YYYY-MM
- **Related Concepts**: [Related documentation link](/docs/...)

## Context

Describe the problems, constraints, and motivations at decision time. Include:

- Specific scenarios or pain points that triggered the decision
- Technical constraints at the time (performance, compliance, team size, etc.)
- The cost of not making this decision

## Decision

State the final choice in 1-3 sentences. For example:

> We decided to sink X as a kernel-native component, with Y providing the unified interface, enforcing Z.

Then expand on 3-5 core reasons, each with 1-2 sentences of explanation.

## Consequences

List in three categories:

**Benefits**:
- Benefit 1
- Benefit 2

**Costs**:
- Cost 1
- Cost 2

**Follow-up Work**:
- Todo 1
- Todo 2

## Alternatives

List considered but unadopted options, each including:

### Option A: Name
- **Description**: Option overview
- **Advantages**: Option benefits
- **Rejection Reason**: Why not adopted

## References

- [Related ADR](/docs/adr/NNNN-xxx)
- [Standard/paper/Issue link]
- Related code crate names

Writing Guidelines

When to Write an ADR

An ADR should be written if any of the following conditions are met:

• Introducing or removing a kernel first-class citizen abstraction (such as topology, constraints, device model)
• Changing the system’s security boundary or trust model
• Selecting a third-party dependency or protocol that affects the entire system
• Interface changes across multiple crates
• Decisions that may be questioned or overturned by future engineers
• Trade-offs involving compliance, performance, or availability

When Not to Write an ADR

An ADR is not required in the following cases:

• Internal implementation details of a single crate (should be written in code comments or crate-level README)
• Bug fixes (should be written in commit messages or PR descriptions)
• Documentation improvements (should directly modify the documentation)
• Temporary experimental features (should be marked as experimental, consider ADR after stabilization)

Writing Principles

1. One decision per ADR: One decision per file, do not merge multiple decisions
2. Immutable: After status becomes “Accepted,” content is no longer modified and can only be superseded by new ADRs
3. Traceable: Each decision must be able to answer “why not another option”
4. Concise: Keep the body to 200-400 lines; lengthy analysis goes in appendices or standalone documents
5. Verifiable: Consequences of decisions should尽量 provide measurable metrics (such as latency, throughput)
6. Linked: Establish explicit references between related ADRs

Decision Process

EnerOS’s architecture decisions follow this process to ensure decisions are both rigorous and efficient:

   ┌──────────────┐
   │ 1. Identify  │  ← Initiated by engineer or architect
   │ decision point│
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │ 2. Draft ADR │  ← Use template, status is "Proposed"
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │ 3. Public    │  ← PR format, at least 2 architects review
   │ review       │
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │ 4. Review    │  ← Approved / Rejected / Needs modification
   │ conclusion   │
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │ 5. Status    │  ← If approved, "Accepted"; otherwise "Rejected"
   │ update       │
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │ 6. Implement │  ← Code implementation + testing + doc sync
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │ 7. Review    │  ← Evaluate decision effectiveness 3-6 months after launch
   └──────────────┘

Review Roles

Review Criteria

Reviews focus on the following dimensions:

• Necessity: Is this decision really needed? What is the cost of maintaining the status quo?
• Sufficiency: Are alternatives considered comprehensively? Are rejection reasons valid?
• Consistency: Does it conflict with existing ADRs? Does it introduce new contradictions?
• Reversibility: Is the decision reversible? If superseded, what is the migration cost?
• Verifiability: Are decision effects measurable? How to evaluate?

Relationship Between ADR and Other Documentation

EnerOS’s documentation system is organized in three layers: “what / why / how.” ADR is in the “why” layer:

ADR is “upstream” of other documentation: concept docs explain terms introduced by ADRs, architecture docs implement ADR decisions, and how-to guides teach users to use capabilities decided by ADRs. When modifying an ADR, check whether downstream documents need updating.

Writing Conventions

• Numbering starts from 0001, increments chronologically, and is not reused
• One decision per file, filename format NNNN-kebab-case-title.md
• Once a decision is superseded, the original file is retained and marked Status: Superseded; the new ADR references the predecessor number
• ADR only records “why this decision was made” and does not duplicate implementation details
• Date precision to month is sufficient; no need for day
• Body uses English, technical terms may retain English (such as mTLS, SPIFFE, RBAC)
• Code examples must be complete and runnable; do not use // ... to omit key logic
• Tables must include complete field descriptions; no empty columns

Tool Support

The EnerOS repository provides the following tools to assist with ADR management:

• scripts/adr-new.sh: Creates a new ADR based on a template, auto-assigns numbering
• scripts/adr-check.sh: Checks format and link validity of all ADRs
• scripts/adr-graph.sh: Generates reference relationship graphs between ADRs

Example usage:

# Create new ADR
./scripts/adr-new.sh "timeseries-engine-selection"

# Check all ADRs
./scripts/adr-check.sh

# Generate relationship graph
./scripts/adr-graph.sh --output docs/adr/graph.svg

Related Documentation

• Core Concepts — Power-Native design philosophy
• Layered Architecture — Architecture overview
• Contributing Guide — How to submit a new ADR
• ADR-0002 — Power-Native AgentOS design decision
• ADR-0007 — Zero Trust & mTLS enforcement decision
• ADR-0010 — Agent intelligence evolution path decision