# ovich/swarmstorm architecture

> Architecture diagram of the GitHub repository ovich/swarmstorm, 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/ovich/swarmstorm
- Repository: https://github.com/ovich/swarmstorm

## Overview

Swarmstorm coordinates coding agents through a shared board and exposes live run activity and project documents in aiview. A typical user asks an orchestrator to run a swarm; agents coordinate through the board, and the user follows the run and reviews its outputs in the browser. The graph emphasizes the board’s CLI/server/store path and aiview’s UI/API path. It also preserves documented protocol, prototype, workbench, and QA capabilities; their implementation details were not sampled, so links to them are not asserted.

Main entry points: [`skills/companions/swarm-board/src/board/board.ts`](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/board/board.ts) (Board state), [`skills/companions/swarm-board/src/cli/index.ts`](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/cli/index.ts) (Swarm CLI), [`skills/companions/swarm-board/src/server/server.ts`](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/server/server.ts) (Board server), [`skills/companions/aiview/app/App.tsx`](https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/App.tsx) (aiview browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Swarm coordination"]
  node_swarm_cli["Swarm CLI<br/>[index.ts]"]
  node_orchestrator["Orchestrator<br/>[orchestrators.ts]"]
  node_agent_link["Agent link<br/>[link.ts]"]
end

subgraph group_board_runtime["Board runtime"]
  node_board_server["Board server<br/>[server.ts]"]
  node_authority["RPC authority<br/>[authority.ts]"]
  node_wire["Wire protocol<br/>[wire.ts]"]
  node_board[("Board state<br/>[board.ts]")]
  node_board_events["Board events<br/>[events.ts]"]
  node_mentions["Mention routing<br/>[mentions.ts]"]
  node_code_pack["Code pack"]
end

subgraph group_viewer["aiview"]
  node_aiview_ui["aiview browser UI<br/>[App.tsx]"]
  node_board_view["Board viewer<br/>[BoardView.tsx]"]
  node_document_viewers["Document viewers"]
  node_document_hook["Document state hook<br/>[useDocuments.ts]"]
  node_web_api["Web API client<br/>[api.ts]"]
end

subgraph group_document_state["Document services"]
  node_http_server["HTTP server<br/>[index.ts]"]
  node_index_store[("Document index<br/>[db.ts]")]
  node_document_paths["Document paths<br/>[paths.ts]"]
  node_sse_hub["Live event stream<br/>[sse.ts]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_protocols["Swarm protocols"]
  node_qa_agents["QA verifiers"]
  node_prototypes["Prototypes<br/>[PrototypeFrame.tsx]"]
  node_workbenches["Workbenches"]
end

node_user(("User"))

node_user -->|"starts swarm"| node_swarm_cli
node_swarm_cli -->|"formats orchestration"| node_orchestrator
node_swarm_cli -->|"issues board calls"| node_board
node_swarm_cli -->|"connects members"| node_agent_link
node_agent_link -.->|"communicates with"| node_board_server
node_board_server -->|"opens board"| node_board
node_board_server -->|"checks calls"| node_authority
node_board_server -->|"encodes frames"| node_wire
node_authority -->|"authorizes methods"| node_board
node_board -->|"parses mentions"| node_mentions
node_board -.->|"records events"| node_board_events
node_board -.->|"dispatches pack"| node_code_pack
node_user -->|"reviews live work"| node_aiview_ui
node_aiview_ui -->|"fetches documents"| node_web_api
node_aiview_ui -->|"renders board"| node_board_view
node_aiview_ui -->|"renders documents"| node_document_viewers
node_document_hook -->|"loads documents"| node_web_api
node_web_api -.->|"requests API"| node_http_server
node_http_server -->|"reads document index"| node_index_store
node_http_server -->|"reads document files"| node_document_paths
node_http_server -->|"creates event hub"| node_sse_hub
node_user -->|"chooses workflow"| node_protocols
node_user -->|"reviews delivery"| node_qa_agents
node_user -->|"approves screens"| node_prototypes
node_user -->|"uses custom tools"| node_workbenches

click node_swarm_cli "https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/cli/index.ts"
click node_orchestrator "https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/cli/answer/orchestrators.ts"
click node_agent_link "https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/link/link.ts"
click node_board_server "https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/server/server.ts"
click node_authority "https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/server/authority.ts"
click node_wire "https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/wire.ts"
click node_board "https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/board/board.ts"
click node_board_events "https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/board/events.ts"
click node_mentions "https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/board/mentions.ts"
click node_code_pack "https://github.com/ovich/swarmstorm/tree/main/skills/companions/swarm-board/src/packs/code"
click node_aiview_ui "https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/App.tsx"
click node_board_view "https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/components/viewers/board/BoardView.tsx"
click node_document_viewers "https://github.com/ovich/swarmstorm/tree/main/skills/companions/aiview/app/components/viewers"
click node_document_hook "https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/hooks/useDocuments.ts"
click node_web_api "https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/lib/api.ts"
click node_http_server "https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/src/server/index.ts"
click node_index_store "https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/src/core/db.ts"
click node_document_paths "https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/src/core/paths.ts"
click node_sse_hub "https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/src/server/sse.ts"
click node_protocols "https://github.com/ovich/swarmstorm/tree/main/skills/companions/swarm-board/src/cli"
click node_qa_agents "https://github.com/ovich/swarmstorm/tree/main/skills"
click node_prototypes "https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/components/viewers/PrototypeFrame.tsx"
click node_workbenches "https://github.com/ovich/swarmstorm/tree/main/skills/workbench/create-workbench"

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_swarm_cli,node_orchestrator,node_agent_link,node_user toneBlue
class node_board_server,node_authority,node_wire,node_board,node_board_events,node_mentions,node_code_pack toneAmber
class node_aiview_ui,node_board_view,node_document_viewers,node_document_hook,node_web_api toneMint
class node_http_server,node_index_store,node_document_paths,node_sse_hub toneRose
class node_protocols,node_qa_agents,node_prototypes,node_workbenches toneIndigo
```

## Components

### Swarm coordination

- [Swarm CLI](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/cli/index.ts): `skills/companions/swarm-board/src/cli/index.ts`
- [Orchestrator](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/cli/answer/orchestrators.ts): `skills/companions/swarm-board/src/cli/answer/orchestrators.ts`
- [Agent link](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/link/link.ts): `skills/companions/swarm-board/src/link/link.ts`

### Board runtime

- [Board server](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/server/server.ts): `skills/companions/swarm-board/src/server/server.ts`
- [RPC authority](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/server/authority.ts): `skills/companions/swarm-board/src/server/authority.ts`
- [Wire protocol](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/wire.ts): `skills/companions/swarm-board/src/wire.ts`
- [Board state](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/board/board.ts): `skills/companions/swarm-board/src/board/board.ts`
- [Board events](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/board/events.ts): `skills/companions/swarm-board/src/board/events.ts`
- [Mention routing](https://github.com/ovich/swarmstorm/blob/main/skills/companions/swarm-board/src/board/mentions.ts): `skills/companions/swarm-board/src/board/mentions.ts`
- [Code pack](https://github.com/ovich/swarmstorm/tree/main/skills/companions/swarm-board/src/packs/code): `skills/companions/swarm-board/src/packs/code`

### aiview

- [aiview browser UI](https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/App.tsx): `skills/companions/aiview/app/App.tsx`
- [Board viewer](https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/components/viewers/board/BoardView.tsx): `skills/companions/aiview/app/components/viewers/board/BoardView.tsx`
- [Document viewers](https://github.com/ovich/swarmstorm/tree/main/skills/companions/aiview/app/components/viewers): `skills/companions/aiview/app/components/viewers`
- [Document state hook](https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/hooks/useDocuments.ts): `skills/companions/aiview/app/hooks/useDocuments.ts`
- [Web API client](https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/lib/api.ts): `skills/companions/aiview/app/lib/api.ts`

### Document services

- [HTTP server](https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/src/server/index.ts): `skills/companions/aiview/src/server/index.ts`
- [Document index](https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/src/core/db.ts): `skills/companions/aiview/src/core/db.ts`
- [Document paths](https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/src/core/paths.ts): `skills/companions/aiview/src/core/paths.ts`
- [Live event stream](https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/src/server/sse.ts): `skills/companions/aiview/src/server/sse.ts`

### Agent capabilities

- [Swarm protocols](https://github.com/ovich/swarmstorm/tree/main/skills/companions/swarm-board/src/cli): `skills/companions/swarm-board/src/cli`
- [QA verifiers](https://github.com/ovich/swarmstorm/tree/main/skills): `skills`
- [Prototypes](https://github.com/ovich/swarmstorm/blob/main/skills/companions/aiview/app/components/viewers/PrototypeFrame.tsx): `skills/companions/aiview/app/components/viewers/PrototypeFrame.tsx`
- [Workbenches](https://github.com/ovich/swarmstorm/tree/main/skills/workbench/create-workbench): `skills/workbench/create-workbench`

### Other components

- **User**

## Connections

- User → Swarm CLI: starts swarm
- Swarm CLI → Orchestrator: formats orchestration (evidence: `skills/companions/swarm-board/src/cli/answer/orchestrators.ts`)
- Swarm CLI → Board state: issues board calls (evidence: `skills/companions/swarm-board/src/cli/index.ts`)
- Swarm CLI → Agent link: connects members (evidence: `skills/companions/swarm-board/src/cli/index.ts`)
- Agent link → Board server: communicates with
- Board server → Board state: opens board (evidence: `skills/companions/swarm-board/src/server/server.ts`)
- Board server → RPC authority: checks calls (evidence: `skills/companions/swarm-board/src/server/server.ts`)
- Board server → Wire protocol: encodes frames (evidence: `skills/companions/swarm-board/src/server/server.ts`)
- RPC authority → Board state: authorizes methods (evidence: `skills/companions/swarm-board/src/server/authority.ts`)
- Board state → Mention routing: parses mentions (evidence: `skills/companions/swarm-board/src/board/board.ts`)
- Board state → Board events: records events (evidence: `skills/companions/swarm-board/src/board/board.ts`)
- Board state → Code pack: dispatches pack
- User → aiview browser UI: reviews live work
- aiview browser UI → Web API client: fetches documents (evidence: `skills/companions/aiview/app/App.tsx`)
- aiview browser UI → Board viewer: renders board (evidence: `skills/companions/aiview/app/App.tsx`)
- aiview browser UI → Document viewers: renders documents (evidence: `skills/companions/aiview/app/App.tsx`)
- Document state hook → Web API client: loads documents (evidence: `skills/companions/aiview/app/hooks/useDocuments.ts`)
- Web API client → HTTP server: requests API
- HTTP server → Document index: reads document index (evidence: `skills/companions/aiview/src/server/index.ts`)
- HTTP server → Document paths: reads document files (evidence: `skills/companions/aiview/src/server/index.ts`)
- HTTP server → Live event stream: creates event hub (evidence: `skills/companions/aiview/src/server/index.ts`)
- User → Swarm protocols: chooses workflow
- User → QA verifiers: reviews delivery
- User → Prototypes: approves screens
- User → Workbenches: uses custom tools
