# m-sec-org/breachweave architecture

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

- Interactive diagram: https://gitdiagram.com/m-sec-org/breachweave
- Repository: https://github.com/m-sec-org/breachweave

## Overview

BreachWeave is a multi-agent penetration-testing system. A user launches a challenge through the web interface or CLI; the Manager coordinates Solver sessions, which explore and submit results, while Observer extensions supervise execution. The web app also manages configuration and presents challenge progress, statistics and attack-flow history. The README documents project/asset management, Planner scheduling, Idea/Memory collaboration, reporting and context reduction; the supplied excerpts do not show every implementation link, so uncertain relationships are omitted.

Main entry points: [`packages/core/src/solver/session.ts`](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/solver/session.ts) (Solver sessions), [`packages/core/src/challenge/manager.ts`](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/manager.ts) (Challenge Manager), [`packages/ui-web/src/server.ts`](https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/server.ts) (Web API), [`packages/core/src/config/index.ts`](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/index.ts) (Config manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[main.ts]"]
  node_webapp["Web app<br/>[app.tsx]"]
end

subgraph group_challenge["Challenge orchestration"]
  node_clientapi["API client<br/>[api-client.ts]"]
  node_manager["Challenge Manager<br/>[manager.ts]"]
  node_timeline[("Attack timeline<br/>[attack-timeline.ts]")]
  node_challengestore[("Challenge store<br/>[store.ts]")]
  node_stats["Challenge stats<br/>[stats.ts]"]
  node_memory[("Challenge memory<br/>[memory.ts]")]
end

subgraph group_agents["Agent execution"]
  node_solver["Solver sessions<br/>[session.ts]"]
  node_board[("Solver board<br/>[board-store.ts]")]
  node_observer["Observer<br/>[observer-loop.ts]"]
  node_extensions["Solver extensions"]
  node_tools["Agent tools<br/>[subagent.ts]"]
  node_ingest["Output ingestion"]
  node_runtime["Runtime types<br/>[types.ts]"]
end

subgraph group_config["Agent configuration"]
  node_config["Config manager<br/>[index.ts]"]
  node_prompts[("Prompt library<br/>[index.ts]")]
  node_skills["Skills<br/>[index.ts]"]
  node_mcp["MCP config<br/>[index.ts]"]
  node_mcpservers["MCP adapter<br/>[server-manager.ts]"]
end

subgraph group_web["Web management"]
  node_challengeui["Challenge console<br/>[page.tsx]"]
  node_attackflow["Attack flow<br/>[attack-flow.tsx]"]
  node_configui["Config pages<br/>[page.tsx]"]
  node_api["Web API<br/>[server.ts]"]
end

node_user(("Operator"))
node_challengeapi{{"Challenge service"}}

node_user -->|"launches"| node_cli
node_user -->|"opens"| node_webapp
node_cli -->|"starts solver"| node_solver
node_webapp -->|"routes to"| node_challengeui
node_webapp -->|"routes to"| node_attackflow
node_webapp -->|"routes to"| node_configui
node_challengeui -->|"requests data"| node_api
node_attackflow -.->|"requests data"| node_api
node_configui -.->|"configures via"| node_api
node_api -->|"dispatches"| node_manager
node_api -->|"reads flow"| node_timeline
node_api -->|"reads stats"| node_stats
node_api -->|"reads snapshot"| node_board
node_manager -->|"submits flags"| node_clientapi
node_manager -->|"persists records"| node_challengestore
node_manager -->|"creates sessions"| node_solver
node_manager -->|"uses settings"| node_config
node_manager -.->|"records activity"| node_timeline
node_manager -.->|"updates metrics"| node_stats
node_clientapi -.->|"calls service"| node_challengeapi
node_solver -->|"loads session config"| node_config
node_solver -->|"loads prompts"| node_prompts
node_solver -->|"installs observer"| node_observer
node_solver -->|"installs extensions"| node_extensions
node_solver -->|"uses types"| node_runtime
node_solver -.->|"invokes tools"| node_tools
node_tools -.->|"accepts output"| node_ingest
node_ingest -.->|"updates hypotheses"| node_memory
node_board -->|"reads memory"| node_memory
node_config -->|"manages prompts"| node_prompts
node_config -->|"loads skills"| node_skills
node_config -->|"loads MCP settings"| node_mcp
node_mcp -.->|"configures servers"| node_mcpservers

click node_cli "https://github.com/m-sec-org/breachweave/blob/main/apps/cli/src/main.ts"
click node_webapp "https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/app.tsx"
click node_challengeui "https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/components/challenge/page.tsx"
click node_attackflow "https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/components/challenge/attack-flow.tsx"
click node_configui "https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/components/config/page.tsx"
click node_api "https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/server.ts"
click node_clientapi "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/api-client.ts"
click node_manager "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/manager.ts"
click node_timeline "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/attack-timeline.ts"
click node_challengestore "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/store.ts"
click node_stats "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/stats.ts"
click node_memory "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/memory.ts"
click node_solver "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/solver/session.ts"
click node_board "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/solver/board-store.ts"
click node_observer "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/solver/extension/challenge-observer/observer-loop.ts"
click node_extensions "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/solver/extension/pentest-compaction.ts"
click node_tools "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/tools/subagent.ts"
click node_ingest "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/tools/ingest-sub-agent-output.ts"
click node_config "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/index.ts"
click node_prompts "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/prompts/index.ts"
click node_skills "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/skills/index.ts"
click node_mcp "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/mcp/index.ts"
click node_mcpservers "https://github.com/m-sec-org/breachweave/blob/main/packages/libs/pi-mcp-adapter/server-manager.ts"
click node_runtime "https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/runtime/types.ts"

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_cli,node_webapp toneBlue
class node_clientapi,node_manager,node_timeline,node_challengestore,node_stats,node_memory toneAmber
class node_solver,node_board,node_observer,node_extensions,node_tools,node_ingest,node_runtime toneMint
class node_config,node_prompts,node_skills,node_mcp,node_mcpservers toneRose
class node_challengeui,node_attackflow,node_configui,node_api,node_user,node_challengeapi toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/m-sec-org/breachweave/blob/main/apps/cli/src/main.ts): `apps/cli/src/main.ts`
- [Web app](https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/app.tsx): `packages/ui-web/src/app.tsx`

### Challenge orchestration

- [API client](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/api-client.ts): `packages/core/src/challenge/api-client.ts`
- [Challenge Manager](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/manager.ts): `packages/core/src/challenge/manager.ts`
- [Attack timeline](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/attack-timeline.ts): `packages/core/src/challenge/attack-timeline.ts`
- [Challenge store](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/store.ts): `packages/core/src/challenge/store.ts`
- [Challenge stats](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/stats.ts): `packages/core/src/challenge/stats.ts`
- [Challenge memory](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/challenge/memory.ts): `packages/core/src/challenge/memory.ts`

### Agent execution

- [Solver sessions](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/solver/session.ts): `packages/core/src/solver/session.ts`
- [Solver board](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/solver/board-store.ts): `packages/core/src/solver/board-store.ts`
- [Observer](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/solver/extension/challenge-observer/observer-loop.ts): `packages/core/src/solver/extension/challenge-observer/observer-loop.ts`
- [Solver extensions](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/solver/extension/pentest-compaction.ts): `packages/core/src/solver/extension/pentest-compaction.ts`
- [Agent tools](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/tools/subagent.ts): `packages/core/src/config/tools/subagent.ts`
- [Output ingestion](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/tools/ingest-sub-agent-output.ts): `packages/core/src/config/tools/ingest-sub-agent-output.ts`
- [Runtime types](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/runtime/types.ts): `packages/core/src/runtime/types.ts`

### Agent configuration

- [Config manager](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/index.ts): `packages/core/src/config/index.ts`
- [Prompt library](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/prompts/index.ts): `packages/core/src/config/prompts/index.ts`
- [Skills](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/skills/index.ts): `packages/core/src/config/skills/index.ts`
- [MCP config](https://github.com/m-sec-org/breachweave/blob/main/packages/core/src/config/mcp/index.ts): `packages/core/src/config/mcp/index.ts`
- [MCP adapter](https://github.com/m-sec-org/breachweave/blob/main/packages/libs/pi-mcp-adapter/server-manager.ts): `packages/libs/pi-mcp-adapter/server-manager.ts`

### Web management

- [Challenge console](https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/components/challenge/page.tsx): `packages/ui-web/src/components/challenge/page.tsx`
- [Attack flow](https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/components/challenge/attack-flow.tsx): `packages/ui-web/src/components/challenge/attack-flow.tsx`
- [Config pages](https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/components/config/page.tsx): `packages/ui-web/src/components/config/page.tsx`
- [Web API](https://github.com/m-sec-org/breachweave/blob/main/packages/ui-web/src/server.ts): `packages/ui-web/src/server.ts`

### Other components

- **Operator**
- **Challenge service**

## Connections

- Operator → CLI: launches (evidence: `apps/cli/src/main.ts`)
- Operator → Web app: opens (evidence: `packages/ui-web/src/app.tsx`)
- CLI → Solver sessions: starts solver (evidence: `apps/cli/src/main.ts`)
- Web app → Challenge console: routes to (evidence: `packages/ui-web/src/app.tsx`)
- Web app → Attack flow: routes to (evidence: `packages/ui-web/src/app.tsx`)
- Web app → Config pages: routes to (evidence: `packages/ui-web/src/app.tsx`)
- Challenge console → Web API: requests data (evidence: `packages/ui-web/src/components/challenge/page.tsx`)
- Attack flow → Web API: requests data
- Config pages → Web API: configures via
- Web API → Challenge Manager: dispatches (evidence: `packages/ui-web/src/server.ts`)
- Web API → Attack timeline: reads flow (evidence: `packages/ui-web/src/server.ts`)
- Web API → Challenge stats: reads stats (evidence: `packages/ui-web/src/server.ts`)
- Web API → Solver board: reads snapshot (evidence: `packages/ui-web/src/server.ts`)
- Challenge Manager → API client: submits flags (evidence: `packages/core/src/challenge/manager.ts`)
- Challenge Manager → Challenge store: persists records (evidence: `packages/core/src/challenge/manager.ts`)
- Challenge Manager → Solver sessions: creates sessions (evidence: `packages/core/src/challenge/manager.ts`)
- Challenge Manager → Config manager: uses settings (evidence: `packages/core/src/challenge/manager.ts`)
- Challenge Manager → Attack timeline: records activity
- Challenge Manager → Challenge stats: updates metrics (evidence: `packages/core/src/challenge/manager.ts`)
- API client → Challenge service: calls service
- Solver sessions → Config manager: loads session config (evidence: `packages/core/src/solver/session.ts`)
- Solver sessions → Prompt library: loads prompts (evidence: `packages/core/src/solver/session.ts`)
- Solver sessions → Observer: installs observer (evidence: `packages/core/src/solver/session.ts`)
- Solver sessions → Solver extensions: installs extensions (evidence: `packages/core/src/solver/session.ts`)
- Solver sessions → Runtime types: uses types (evidence: `packages/core/src/solver/session.ts`)
- Solver sessions → Agent tools: invokes tools
- Agent tools → Output ingestion: accepts output
- Output ingestion → Challenge memory: updates hypotheses
- Solver board → Challenge memory: reads memory (evidence: `packages/core/src/solver/board-store.ts`)
- Config manager → Prompt library: manages prompts (evidence: `packages/core/src/config/index.ts`)
- Config manager → Skills: loads skills (evidence: `packages/core/src/config/index.ts`)
- Config manager → MCP config: loads MCP settings (evidence: `packages/core/src/config/index.ts`)
- MCP config → MCP adapter: configures servers
