Architecture

Overview

R2R and EAC implement a container-based, contract-driven architecture for everything-as-code workflows. The system uses multiple execution models optimized for different use cases: isolated Docker containers for reproducibility, direct Go execution for speed, and MCP protocol for AI integration.

Core architecture: CLI → Extension Container → Core Libraries → Repository

Viewing Architecture Diagrams

All architecture diagrams referenced in this document can be viewed interactively using Structurizr:

r2r eac serve design
# Opens http://localhost:8080

Design files:

• eac-commands: specs/eac-commands/.design/
• eac-core: specs/eac-core/.design/
• eac-mcp-commands: specs/eac-mcp-commands/.design/
• r2r-cli: specs/r2r-cli/.design/
• ext-eac: specs/ext-eac/.design/

See Viewing Architecture for detailed instructions.

System Diagram

Component Layers

R2R CLI

Purpose: Containerized workflow execution framework

Package: Binary (r2r, r2r.exe)

Responsibilities

Configuration

File: .r2r/r2r-cli.yml

extensions:
  - name: eac
    image: ext-eac:latest
    load_local: true  # Build locally for development

Features:

• Cross-platform (Windows, macOS, Linux)
• Docker-based extension execution
• Git-aware working directory mounting
• Configurable extension management

EAC Extension

Purpose: Everything-as-code command collection

Package: ext-eac:latest Docker container

Modules

Container Structure

ext-eac:latest
├── /app/eac              # Compiled commands binary
├── /workspace            # Mounted repository (volume)
└── /usr/local/bin        # System dependencies (git, gh, etc.)

eac-commands

Purpose: Command handler implementations

Commands organized by category:

Command Pattern

// All commands follow this pattern
type BuildHandler struct {
    repo *Repository  // From eac-core
}

func (h *BuildHandler) Execute(args []string) error {
    // 1. Load contracts from .r2r/eac/
    // 2. Resolve dependencies using eac-core
    // 3. Execute build logic
    // 4. Verify artifacts and update cache
    return nil
}

eac-core

Purpose: Core domain libraries and contract system

Core Packages

Repository Registry

// Central registry for all modules and contracts
type Repository struct {
    Modules      map[string]*Module
    ModuleTypes  map[string]*ModuleType
    Environments map[string]*Environment
    TestSuites   map[string]*TestSuite
    Dependencies *DependencyGraph
}

Responsibilities:

• Load all YAML contracts from .r2r/eac/
• Validate contracts against JSON schemas
• Build module dependency graph
• Resolve topological build order
• Manage build cache and artifacts

AI Integration (within eac-commands)

Purpose: AI provider integrations for automated workflows

Location: Integrated within eac-commands module at go/eac/commands/internal/ai/

Supported Providers

Configuration

File: .r2r/eac/ai-config.yml

provider: anthropic
model: claude-sonnet-4
api_key_env: ANTHROPIC_API_KEY

Features:

• Generate commit messages from staged changes
• Create Gherkin specifications from natural language
• Generate Structurizr architecture designs
• Generate pull request descriptions

Implementation:

• Provider implementations: go/eac/commands/internal/ai/providers/
• Configuration loading: go/eac/commands/internal/ai/config_loader.go
• AI execution: go/eac/commands/internal/ai/executor.go

eac-specs

Purpose: BDD test infrastructure and OSCAL compliance

Components

Test Layers

1. Feature Files (.feature) - Gherkin specifications in specs/
2. Step Definitions (.go) - Go implementations in module tests/ folders
3. Unit Tests (*_test.go) - Go unit tests alongside source code

eac-mcp-commands

Purpose: MCP server for LLM tool integration

Protocol: stdio-based JSON-RPC (MCP 1.0)

Compatible with: Any MCP-compatible LLM tool (Claude Code, Cline, Zed, Cursor, etc.)

MCP Tools

command tools exposed as mcp__commands__*:

{
  "name": "mcp__commands__build",
  "description": "Build one or more modules by moniker",
  "inputSchema": {
    "type": "object",
    "properties": {
      "args": {"type": "string"}
    }
  }
}

Configuration

File: .mcp.json or LLM-specific config (e.g., .claude/settings.json for Claude Code)

{
  "mcpServers": {
    "commands": {
      "command": "go",
      "args": ["run", "./go/eac/mcp/commands/main.go"]
    }
  }
}

Benefits:

• Fast execution (~100ms vs ~2s Docker overhead)
• Structured JSON I/O for AI tools
• AI-optimized metadata and descriptions
• Real-time validation feedback
• Works with any MCP-compatible LLM tool

Security Architecture

Isolation

• Containers: Extensions run in isolated Docker containers
• File Access: Minimal read/write permissions via volume mounts
• Network: Limited network access in containers

Scanning

• Pre-build: Secret detection, dependency scanning
• Post-build: Vulnerability scanning, SBOM generation
• Runtime: DAST scanning in test environments

Evidence Collection

• OSCAL: Automated compliance evidence in out/evidence/
• Artifacts: All build/test artifacts in out/
• Audit Logs: Immutable logs in out/logs/

Configuration Management

Configuration Hierarchy

Precedence (highest to lowest):

1. Personal config (.personal.yml, not in Git)
2. Shared config (.yml files in .r2r/eac/)
3. Type defaults (from module-types.yml)
4. System defaults (hardcoded in eac-core)

Technology Stack

Go Ecosystem

External Tools

Performance & Scalability

Parallel Execution

• Build: Topological sort enables parallel module builds
• Test: Test suites run in parallel by default
• CI: GitHub Actions matrix strategy for cross-platform

Caching

• Docker: Layer caching for fast image builds
• Build: Artifact cache in .r2r/cache/ for incremental builds
• Go: Module cache for dependency downloads
• Git: Change detection to skip unchanged modules

Related Documentation

• Overview - System overview and key concepts
• Contracts - Contract system and YAML schemas
• Modules - Module system and types

Tutorials | How-to Guides | Explanation | Reference

You are here: Reference — information-oriented technical descriptions of the system.