# affaan-m/ecc architecture

> Architecture diagram of the GitHub repository affaan-m/ecc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/affaan-m/ecc
- Repository: https://github.com/affaan-m/ecc
- Video tour (about a minute): https://gitdiagram.com/affaan-m/ecc/video

## Overview

ECC is a harness-native agent operating system: users configure and launch agent sessions, coordinate work, and inspect execution through a terminal dashboard. The Rust `ecc2` runtime provides session management, persistence, communication, worktrees, notifications, and observability; the repository also includes evaluation tooling for measuring agent and Guard behavior. The graph emphasizes these supported runtime stages. Some subsystem wiring is inferred only from the SOURCE INDEX references, so unsampled implementation details and optional integrations are not expanded.

Main entry points: [`ecc2/src/main.rs`](https://github.com/affaan-m/ecc/blob/main/ecc2/src/main.rs) (ECC CLI), [`ecc2/src/session/manager.rs`](https://github.com/affaan-m/ecc/blob/main/ecc2/src/session/manager.rs) (Session manager), [`ecc2/src/session/store.rs`](https://github.com/affaan-m/ecc/blob/main/ecc2/src/session/store.rs) (State store), [`ecc2/src/tui/app.rs`](https://github.com/affaan-m/ecc/blob/main/ecc2/src/tui/app.rs) (Terminal dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Session runtime"]
  node_ecc_cli["ECC CLI<br/>[main.rs]"]
  node_config["Configuration<br/>[mod.rs]"]
  node_session_manager["Session manager<br/>[manager.rs]"]
  node_session_runtime["Session runtime<br/>[runtime.rs]"]
  node_session_daemon["Session daemon<br/>[daemon.rs]"]
  node_state_store[("State store<br/>[store.rs]")]
  node_worktrees["Worktrees<br/>[mod.rs]"]
end

subgraph group_coordination["Agent coordination"]
  node_comms["Agent messaging<br/>[mod.rs]"]
  node_notifications["Notifications<br/>[notifications.rs]"]
  node_observability["Observability<br/>[mod.rs]"]
end

subgraph group_operations["Operator interface"]
  node_tui["Terminal dashboard<br/>[app.rs]"]
  node_dashboard_view["Dashboard view<br/>[dashboard.rs]"]
end

subgraph group_evaluation["Evaluation tools"]
  node_harness_eval["Harness evaluator<br/>[harness_eval.rs]"]
  node_eval_library["AI evaluation library<br/>[ai-eval-lib.js]"]
  node_guard_eval["Guard evaluation<br/>[lib.js]"]
  node_guard_arms["Guard variants<br/>[arms.js]"]
  node_ticket_service["Ticket service<br/>[service.js]"]
  node_ticket_routes["Ticket routes<br/>[routes.js]"]
end

node_operator(("Operator"))

node_operator -->|"starts sessions"| node_ecc_cli
node_ecc_cli -->|"loads configuration"| node_config
node_ecc_cli -->|"manages sessions"| node_session_manager
node_ecc_cli -->|"accesses state"| node_state_store
node_ecc_cli -->|"uses messaging"| node_comms
node_ecc_cli -->|"uses notifications"| node_notifications
node_ecc_cli -->|"uses telemetry"| node_observability
node_ecc_cli -->|"launches dashboard"| node_tui
node_ecc_cli -->|"runs evaluation"| node_harness_eval
node_session_manager -->|"reads settings"| node_config
node_session_manager -->|"starts runners"| node_session_runtime
node_session_manager -->|"persists sessions"| node_state_store
node_session_manager -->|"manages worktrees"| node_worktrees
node_session_manager -->|"coordinates agents"| node_comms
node_session_manager -->|"sends notices"| node_notifications
node_session_manager -->|"records activity"| node_observability
node_tui -->|"renders view"| node_dashboard_view
node_tui -->|"reads session state"| node_state_store
node_observability -->|"logs tool calls"| node_state_store
node_comms -->|"stores messages"| node_state_store
node_guard_eval -->|"runs scored checks"| node_eval_library
node_guard_eval -->|"compares variants"| node_guard_arms
node_ticket_routes -->|"dispatches requests"| node_ticket_service

click node_ecc_cli "https://github.com/affaan-m/ecc/blob/main/ecc2/src/main.rs"
click node_config "https://github.com/affaan-m/ecc/blob/main/ecc2/src/config/mod.rs"
click node_session_manager "https://github.com/affaan-m/ecc/blob/main/ecc2/src/session/manager.rs"
click node_session_runtime "https://github.com/affaan-m/ecc/blob/main/ecc2/src/session/runtime.rs"
click node_session_daemon "https://github.com/affaan-m/ecc/blob/main/ecc2/src/session/daemon.rs"
click node_state_store "https://github.com/affaan-m/ecc/blob/main/ecc2/src/session/store.rs"
click node_worktrees "https://github.com/affaan-m/ecc/blob/main/ecc2/src/worktree/mod.rs"
click node_comms "https://github.com/affaan-m/ecc/blob/main/ecc2/src/comms/mod.rs"
click node_notifications "https://github.com/affaan-m/ecc/blob/main/ecc2/src/notifications.rs"
click node_observability "https://github.com/affaan-m/ecc/blob/main/ecc2/src/observability/mod.rs"
click node_tui "https://github.com/affaan-m/ecc/blob/main/ecc2/src/tui/app.rs"
click node_dashboard_view "https://github.com/affaan-m/ecc/blob/main/ecc2/src/tui/dashboard.rs"
click node_harness_eval "https://github.com/affaan-m/ecc/blob/main/ecc2/src/harness_eval.rs"
click node_eval_library "https://github.com/affaan-m/ecc/blob/main/docker/context-profiles/ai-eval-lib.js"
click node_guard_eval "https://github.com/affaan-m/ecc/blob/main/docker/gateguard-effectiveness/lib.js"
click node_guard_arms "https://github.com/affaan-m/ecc/blob/main/docker/gateguard-effectiveness/arms.js"
click node_ticket_service "https://github.com/affaan-m/ecc/blob/main/docker/context-profiles/complex-eval/reference3/chained-tickets/src/service.js"
click node_ticket_routes "https://github.com/affaan-m/ecc/blob/main/docker/context-profiles/complex-eval/reference3/chained-tickets/src/routes.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ecc_cli,node_config,node_session_manager,node_session_runtime,node_session_daemon,node_state_store,node_worktrees toneBlue
class node_comms,node_notifications,node_observability toneAmber
class node_tui,node_dashboard_view toneMint
class node_harness_eval,node_eval_library,node_guard_eval,node_guard_arms,node_ticket_service,node_ticket_routes toneRose
class node_operator toneIndigo
```

## Components

### Session runtime

- [ECC CLI](https://github.com/affaan-m/ecc/blob/main/ecc2/src/main.rs): `ecc2/src/main.rs`
- [Configuration](https://github.com/affaan-m/ecc/blob/main/ecc2/src/config/mod.rs): `ecc2/src/config/mod.rs`
- [Session manager](https://github.com/affaan-m/ecc/blob/main/ecc2/src/session/manager.rs): `ecc2/src/session/manager.rs`
- [Session runtime](https://github.com/affaan-m/ecc/blob/main/ecc2/src/session/runtime.rs): `ecc2/src/session/runtime.rs`
- [Session daemon](https://github.com/affaan-m/ecc/blob/main/ecc2/src/session/daemon.rs): `ecc2/src/session/daemon.rs`
- [State store](https://github.com/affaan-m/ecc/blob/main/ecc2/src/session/store.rs): `ecc2/src/session/store.rs`
- [Worktrees](https://github.com/affaan-m/ecc/blob/main/ecc2/src/worktree/mod.rs): `ecc2/src/worktree/mod.rs`

### Agent coordination

- [Agent messaging](https://github.com/affaan-m/ecc/blob/main/ecc2/src/comms/mod.rs): `ecc2/src/comms/mod.rs`
- [Notifications](https://github.com/affaan-m/ecc/blob/main/ecc2/src/notifications.rs): `ecc2/src/notifications.rs`
- [Observability](https://github.com/affaan-m/ecc/blob/main/ecc2/src/observability/mod.rs): `ecc2/src/observability/mod.rs`

### Operator interface

- [Terminal dashboard](https://github.com/affaan-m/ecc/blob/main/ecc2/src/tui/app.rs): `ecc2/src/tui/app.rs`
- [Dashboard view](https://github.com/affaan-m/ecc/blob/main/ecc2/src/tui/dashboard.rs): `ecc2/src/tui/dashboard.rs`

### Evaluation tools

- [Harness evaluator](https://github.com/affaan-m/ecc/blob/main/ecc2/src/harness_eval.rs): `ecc2/src/harness_eval.rs`
- [AI evaluation library](https://github.com/affaan-m/ecc/blob/main/docker/context-profiles/ai-eval-lib.js): `docker/context-profiles/ai-eval-lib.js`
- [Guard evaluation](https://github.com/affaan-m/ecc/blob/main/docker/gateguard-effectiveness/lib.js): `docker/gateguard-effectiveness/lib.js`
- [Guard variants](https://github.com/affaan-m/ecc/blob/main/docker/gateguard-effectiveness/arms.js): `docker/gateguard-effectiveness/arms.js`
- [Ticket service](https://github.com/affaan-m/ecc/blob/main/docker/context-profiles/complex-eval/reference3/chained-tickets/src/service.js): `docker/context-profiles/complex-eval/reference3/chained-tickets/src/service.js`
- [Ticket routes](https://github.com/affaan-m/ecc/blob/main/docker/context-profiles/complex-eval/reference3/chained-tickets/src/routes.js): `docker/context-profiles/complex-eval/reference3/chained-tickets/src/routes.js`

### Other components

- **Operator**

## Connections

- Operator → ECC CLI: starts sessions (evidence: `ecc2/src/main.rs`)
- ECC CLI → Configuration: loads configuration (evidence: `ecc2/src/main.rs`)
- ECC CLI → Session manager: manages sessions (evidence: `ecc2/src/main.rs`)
- ECC CLI → State store: accesses state (evidence: `ecc2/src/main.rs`)
- ECC CLI → Agent messaging: uses messaging (evidence: `ecc2/src/main.rs`)
- ECC CLI → Notifications: uses notifications (evidence: `ecc2/src/main.rs`)
- ECC CLI → Observability: uses telemetry (evidence: `ecc2/src/main.rs`)
- ECC CLI → Terminal dashboard: launches dashboard (evidence: `ecc2/src/main.rs`)
- ECC CLI → Harness evaluator: runs evaluation (evidence: `ecc2/src/main.rs`)
- Session manager → Configuration: reads settings (evidence: `ecc2/src/session/manager.rs`)
- Session manager → Session runtime: starts runners (evidence: `ecc2/src/session/manager.rs`)
- Session manager → State store: persists sessions (evidence: `ecc2/src/session/manager.rs`)
- Session manager → Worktrees: manages worktrees (evidence: `ecc2/src/session/manager.rs`)
- Session manager → Agent messaging: coordinates agents (evidence: `ecc2/src/session/manager.rs`)
- Session manager → Notifications: sends notices (evidence: `ecc2/src/session/manager.rs`)
- Session manager → Observability: records activity (evidence: `ecc2/src/session/manager.rs`)
- Terminal dashboard → Dashboard view: renders view (evidence: `ecc2/src/tui/app.rs`)
- Terminal dashboard → State store: reads session state (evidence: `ecc2/src/tui/app.rs`)
- Observability → State store: logs tool calls (evidence: `ecc2/src/observability/mod.rs`)
- Agent messaging → State store: stores messages (evidence: `ecc2/src/comms/mod.rs`)
- Guard evaluation → AI evaluation library: runs scored checks (evidence: `docker/gateguard-effectiveness/lib.js`)
- Guard evaluation → Guard variants: compares variants (evidence: `docker/gateguard-effectiveness/lib.js`)
- Ticket routes → Ticket service: dispatches requests (evidence: `docker/context-profiles/complex-eval/reference3/chained-tickets/src/routes.js`)
