# b-3llum/ice-9 architecture

> Architecture diagram of the GitHub repository b-3llum/ice-9, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/b-3llum/ice-9
- Repository: https://github.com/b-3llum/ice-9

## Overview

ice_9 is a MITRE ATT&CK-aligned red-team campaign platform. Operators manage campaigns through the CLI or React dashboard; campaign phases run integrated tools, findings and intel are recorded, and teams can plan or autonomously select phases. Results are exposed through REST and live events and can feed reporting. The graph combines README-described capabilities with sampled API, dashboard, autopilot, LLM, and storage behavior; unsampled subsystem connections are shown only where documented.

Main entry points: [`ice_9/api.py`](https://github.com/b-3llum/ice-9/blob/main/ice_9/api.py) (REST API), [`ice_9/phases`](https://github.com/b-3llum/ice-9/tree/main/ice_9/phases) (ATT&CK phase engine), [`ice_9/db/store.py`](https://github.com/b-3llum/ice-9/blob/main/ice_9/db/store.py) (Campaign and intel store), [`ice_9/ai/orchestrator.py`](https://github.com/b-3llum/ice-9/blob/main/ice_9/ai/orchestrator.py) (Campaign autopilot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Operator interfaces"]
  node_dashboard["Web dashboard<br/>[App.tsx]"]
  node_dashboard_api["Dashboard API client<br/>[client.ts]"]
  node_event_stream["Live event stream<br/>[useEventStream.ts]"]
  node_cli["Campaign CLI<br/>[cli.py]"]
end

subgraph group_service["API and events"]
  node_api["REST API<br/>[api.py]"]
  node_event_bus["Event bus<br/>[events.py]"]
end

subgraph group_campaign["Campaign execution"]
  node_phase_engine["ATT&amp;CK phase engine"]
  node_tool_runner["Tool runner<br/>[execution.py]"]
  node_intel_pipeline["Intel extraction and profiling"]
  node_simulation["Subject simulation<br/>[simulation.py]"]
end

subgraph group_intelligence["AI and intel"]
  node_ai_orchestrator["Campaign autopilot<br/>[orchestrator.py]"]
  node_ai_team["AI agent team<br/>[team.py]"]
  node_model_router["Model router<br/>[router.py]"]
  node_llm_client["LLM client<br/>[llm.py]"]
  node_rag[("RAG knowledge base")]
end

subgraph group_state["Persistence and reporting"]
  node_store[("Campaign and intel store<br/>[store.py]")]
  node_reporting["Report generation<br/>[generator.py]"]
  node_audit[("Audit logging<br/>[audit.py]")]
end

node_operator(("Operator"))
node_offensive_tools["Offensive tools"]
node_providers["LLM providers"]

node_operator -->|"uses"| node_dashboard
node_operator -->|"runs"| node_cli
node_dashboard -->|"requests data"| node_dashboard_api
node_dashboard_api -->|"REST calls"| node_api
node_dashboard -->|"subscribes"| node_event_stream
node_event_stream -->|"opens SSE"| node_api
node_cli -->|"runs phases"| node_phase_engine
node_api -->|"dispatches phases"| node_phase_engine
node_api -->|"dispatches AI"| node_ai_team
node_api -->|"dispatches tools"| node_tool_runner
node_phase_engine -->|"runs tools"| node_tool_runner
node_tool_runner -->|"invokes"| node_offensive_tools
node_phase_engine -->|"extracts findings"| node_intel_pipeline
node_ai_orchestrator -->|"asks and analyzes"| node_ai_team
node_ai_orchestrator -->|"selects and runs"| node_phase_engine
node_ai_orchestrator -->|"reloads campaign"| node_store
node_ai_orchestrator -->|"records actions"| node_audit
node_ai_team -->|"routes tasks"| node_model_router
node_model_router -->|"selects provider"| node_llm_client
node_llm_client -->|"sends prompts"| node_providers
node_ai_team -.->|"uses knowledge"| node_rag
node_phase_engine -->|"persists campaign state"| node_store
node_intel_pipeline -->|"stores intel"| node_store
node_simulation -->|"uses subject profiles"| node_store
node_api -->|"publishes events"| node_event_bus
node_event_bus -->|"streams events"| node_event_stream
node_reporting -->|"reads campaign results"| node_store
node_cli -->|"generates reports"| node_reporting

click node_dashboard "https://github.com/b-3llum/ice-9/blob/main/dashboard/src/App.tsx"
click node_dashboard_api "https://github.com/b-3llum/ice-9/blob/main/dashboard/src/api/client.ts"
click node_event_stream "https://github.com/b-3llum/ice-9/blob/main/dashboard/src/hooks/useEventStream.ts"
click node_cli "https://github.com/b-3llum/ice-9/blob/main/ice_9/cli.py"
click node_api "https://github.com/b-3llum/ice-9/blob/main/ice_9/api.py"
click node_event_bus "https://github.com/b-3llum/ice-9/blob/main/ice_9/core/events.py"
click node_phase_engine "https://github.com/b-3llum/ice-9/tree/main/ice_9/phases"
click node_tool_runner "https://github.com/b-3llum/ice-9/blob/main/ice_9/tools/execution.py"
click node_intel_pipeline "https://github.com/b-3llum/ice-9/tree/main/ice_9/intel"
click node_simulation "https://github.com/b-3llum/ice-9/blob/main/ice_9/intel/simulation.py"
click node_ai_orchestrator "https://github.com/b-3llum/ice-9/blob/main/ice_9/ai/orchestrator.py"
click node_ai_team "https://github.com/b-3llum/ice-9/blob/main/ice_9/ai/team.py"
click node_model_router "https://github.com/b-3llum/ice-9/blob/main/ice_9/ai/router.py"
click node_llm_client "https://github.com/b-3llum/ice-9/blob/main/ice_9/ai/llm.py"
click node_rag "https://github.com/b-3llum/ice-9/tree/main/ice_9/ai/rag"
click node_store "https://github.com/b-3llum/ice-9/blob/main/ice_9/db/store.py"
click node_reporting "https://github.com/b-3llum/ice-9/blob/main/ice_9/reporting/generator.py"
click node_audit "https://github.com/b-3llum/ice-9/blob/main/ice_9/core/audit.py"

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_dashboard,node_dashboard_api,node_event_stream,node_cli toneBlue
class node_api,node_event_bus toneAmber
class node_phase_engine,node_tool_runner,node_intel_pipeline,node_simulation toneMint
class node_ai_orchestrator,node_ai_team,node_model_router,node_llm_client,node_rag toneRose
class node_store,node_reporting,node_audit,node_operator,node_offensive_tools,node_providers toneIndigo
```

## Components

### Operator interfaces

- [Web dashboard](https://github.com/b-3llum/ice-9/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Dashboard API client](https://github.com/b-3llum/ice-9/blob/main/dashboard/src/api/client.ts): `dashboard/src/api/client.ts`
- [Live event stream](https://github.com/b-3llum/ice-9/blob/main/dashboard/src/hooks/useEventStream.ts): `dashboard/src/hooks/useEventStream.ts`
- [Campaign CLI](https://github.com/b-3llum/ice-9/blob/main/ice_9/cli.py): `ice_9/cli.py`

### API and events

- [REST API](https://github.com/b-3llum/ice-9/blob/main/ice_9/api.py): `ice_9/api.py`
- [Event bus](https://github.com/b-3llum/ice-9/blob/main/ice_9/core/events.py): `ice_9/core/events.py`

### Campaign execution

- [ATT&CK phase engine](https://github.com/b-3llum/ice-9/tree/main/ice_9/phases): `ice_9/phases`
- [Tool runner](https://github.com/b-3llum/ice-9/blob/main/ice_9/tools/execution.py): `ice_9/tools/execution.py`
- [Intel extraction and profiling](https://github.com/b-3llum/ice-9/tree/main/ice_9/intel): `ice_9/intel`
- [Subject simulation](https://github.com/b-3llum/ice-9/blob/main/ice_9/intel/simulation.py): `ice_9/intel/simulation.py`

### AI and intel

- [Campaign autopilot](https://github.com/b-3llum/ice-9/blob/main/ice_9/ai/orchestrator.py): `ice_9/ai/orchestrator.py`
- [AI agent team](https://github.com/b-3llum/ice-9/blob/main/ice_9/ai/team.py): `ice_9/ai/team.py`
- [Model router](https://github.com/b-3llum/ice-9/blob/main/ice_9/ai/router.py): `ice_9/ai/router.py`
- [LLM client](https://github.com/b-3llum/ice-9/blob/main/ice_9/ai/llm.py): `ice_9/ai/llm.py`
- [RAG knowledge base](https://github.com/b-3llum/ice-9/tree/main/ice_9/ai/rag): `ice_9/ai/rag`

### Persistence and reporting

- [Campaign and intel store](https://github.com/b-3llum/ice-9/blob/main/ice_9/db/store.py): `ice_9/db/store.py`
- [Report generation](https://github.com/b-3llum/ice-9/blob/main/ice_9/reporting/generator.py): `ice_9/reporting/generator.py`
- [Audit logging](https://github.com/b-3llum/ice-9/blob/main/ice_9/core/audit.py): `ice_9/core/audit.py`

### Other components

- **Operator**
- **Offensive tools**
- **LLM providers**

## Connections

- Operator → Web dashboard: uses
- Operator → Campaign CLI: runs
- Web dashboard → Dashboard API client: requests data
- Dashboard API client → REST API: REST calls
- Web dashboard → Live event stream: subscribes
- Live event stream → REST API: opens SSE
- Campaign CLI → ATT&CK phase engine: runs phases
- REST API → ATT&CK phase engine: dispatches phases
- REST API → AI agent team: dispatches AI
- REST API → Tool runner: dispatches tools
- ATT&CK phase engine → Tool runner: runs tools
- Tool runner → Offensive tools: invokes
- ATT&CK phase engine → Intel extraction and profiling: extracts findings
- Campaign autopilot → AI agent team: asks and analyzes
- Campaign autopilot → ATT&CK phase engine: selects and runs
- Campaign autopilot → Campaign and intel store: reloads campaign
- Campaign autopilot → Audit logging: records actions
- AI agent team → Model router: routes tasks
- Model router → LLM client: selects provider
- LLM client → LLM providers: sends prompts
- AI agent team → RAG knowledge base: uses knowledge
- ATT&CK phase engine → Campaign and intel store: persists campaign state
- Intel extraction and profiling → Campaign and intel store: stores intel
- Subject simulation → Campaign and intel store: uses subject profiles
- REST API → Event bus: publishes events
- Event bus → Live event stream: streams events
- Report generation → Campaign and intel store: reads campaign results
- Campaign CLI → Report generation: generates reports