# ruvnet/claude-flow architecture

> Architecture diagram of the GitHub repository ruvnet/claude-flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ruvnet/claude-flow
- Repository: https://github.com/ruvnet/claude-flow

## Overview

##### Project Type and Purpose
- Claude-Flow v2.0.0 Alpha is an enterprise-grade AI orchestration platform: a monorepo combining a rich CLI, core libraries, an event-driven coordination engine (“hive-mind”), distributed memory, neural tooling, MCP services, web and console UIs, and integration hooks.
- It’s a developer toolchain rather than a traditional webapp, organized as a full-stack application (CLI front-end + core “backend” libraries + optional UIs).

##### High-Level File Structure Analysis
- Top-level modules:
- /bin & /src/cli → Command-line interface, command registry, scripts.
- /src/core, /src/coordination, /src/swarm, /src/task → Event-bus, orchestrator, task scheduling, swarm orchestration libraries.
- /src/agents & /src/hive-mind → Queen + worker agent implementations and communication protocols.
- /src/memory & /memory → Distributed memory manager, backends (SQLite, markdown), cache, replication.
- /src/mcp → MCP server, transports (HTTP/STDIO), protocol manager for tool integration.
- /src/ui/console & /src/ui/web-ui → Console-based and web-based user interfaces.
- /scripts, /.claude/hooks → Build/test scripts and hooks system.
- /infrastructure/docker → Docker-based deployment of Hive-Mind DB and MCP servers.

##### README Insights
- The architecture overview lists these logical layers:
- Hive-Mind Coordination Layer (Queen + worker agents)
- Neural Pattern Recognition Layer
- Distributed Memory System
- 87 MCP Tools Integration Layer
- Claude Code Integration Layer
- Key tech: Node.js/TypeScript, WASM for neural acceleration, SQLite for persistence, pub/sub event bus, Cliffy CLI framework, Docker.

##### Main Components
a. **CLI Front-End**:
- Input: bin scripts, `src/cli` modules
- Interacts via Command Registry → Core Orchestrator
b. **Core Orchestration Engine**:
- `src/core/event-bus`, `orchestrator`, `json-persistence`, `logger`
- Publishes tasks to Coordination Manager
c. **Coordination Layer**:
- `src/coordination`: scheduler, swarm-coordinator, load-balancer, messaging
- Implements hierarchical, mesh, hybrid strategies
d. **Agent Framework (Hive-Mind)**:
- `src/hive-mind/core`: Queen, Agents, MemoryMonitor, Communication
- `src/agents`: agent registry, manager
e. **Task Execution (Swarm)**:
- `src/swarm`: executors, optimizations, prompt manager
f. **Memory & Persistence**:
- `src/memory` + `/memory` package: backends, cache, indexer, replication
- Hive-Mind DB (SQLite) under `.hive-mind`
g. **Neural/Pattern Layer**:
- WASM modules invoked by CLI & core for pattern training/prediction
h. **MCP Services**:
- `src/mcp`: HTTP/STDIO transports, protocol management, session manager
i. **UI Layers**:
- Console UI: websockets via `src/ui/console/js`
- Web UI: React-style components under `src/ui/web-ui` using EventBus & MCPIntegrationLayer
j. **External Integrations**:
- GitHub (via `src/cli/commands/github`), Docker, filesystems, network

##### Relationships & Data Flow
1. **User** issues a CLI command → CLI front-end parses & routes to Command Registry.
2. CLI invokes **Core Orchestrator** → emits events on Event Bus.
3. **Coordination Manager** subscribes → schedules tasks via Swarm or Hive-Mind layers.
4. **Queen Agent** spawns worker Agents → Agents execute tasks using Swarm executors or MCP Tools.
5. Agents read/write from **Distributed Memory** and **Hive-Mind DB**.
6. Neural modules may be invoked for pattern recognition/training via WASM.
7. Results aggregated by Core’s Result Aggregator → CLI prints or pushes updates to UIs.
8. CLI/UI can connect to MCP Server for programmatic integrations.

##### Architectural Patterns & Principles
- Layered architecture: CLI → Core → Coordination → Agents → Memory/DB
- Event-driven & pub/sub: `event-bus`, `message-bus`
- Plugin‐based CLI: each command is a module under `src/cli/commands`
- Hexagonal boundaries: core libraries are decoupled from transport & persistence
- Microservices‐style “modules” (Memory, MCP, Hive-Mind) communicating via interfaces

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% CLI Front-End
  subgraph "CLI Front-End"
    CLI_bin["bin scripts"]:::cli
    CLI_src["src/cli modules"]:::cli
  end

  %% Core Orchestration Engine
  subgraph "Core Orchestration Engine"
    EventBus["Event Bus"]:::core
    Orchestrator["Orchestrator"]:::core
    JSONPers["JSON Persistence"]:::core
    Logger["Logger"]:::core
    Persistence["Persistence"]:::core
  end

  %% Coordination Layer
  subgraph "Coordination Layer"
    Scheduler["Scheduler"]:::coord
    SwarmCoord["Swarm Coordinator"]:::coord
    LoadBalancer["Load Balancer"]:::coord
    Messaging["Messaging"]:::coord
    Manager["Coordination Manager"]:::coord
  end

  %% Agent Framework (Hive-Mind)
  subgraph "Agent Framework (Hive-Mind)"
    Queen["Queen Agent"]:::agent
    AgentCore["Agent"]:::agent
    Comm["Communication"]:::agent
    MemMon["Memory Monitor"]:::agent
    DBMgr["Database Manager"]:::agent
    AgentMgr["Agent Manager"]:::agent
    AgentReg["Agent Registry"]:::agent
  end

  %% Task Execution (Swarm)
  subgraph "Task Execution (Swarm)"
    SwarmIndex["Swarm Index"]:::swarm
    Executor["Executor"]:::swarm
    ExecutorV2["Executor v2"]:::swarm
    DirectExec["Direct Executor"]:::swarm
    PromptMgr["Prompt Manager"]:::swarm
  end

  %% Memory & Persistence
  subgraph "Memory & Persistence"
    SQLiteBE["SQLite Backend"]:::mem
    MD_BE["Markdown Backend"]:::mem
    MemMgr["Memory Manager"]:::mem
    Indexer["Indexer"]:::mem
    Replication["Replication"]:::mem
    Hivedb["Hive-Mind DB"]:::mem
  end

  %% MCP Services
  subgraph "MCP Services"
    MCPServer["MCP Server"]:::mcp
    HTTPTrans["HTTP Transport"]:::mcp
    SDTOTrans["STDIO Transport"]:::mcp
    ProtocolMgr["Protocol Manager"]:::mcp
    SessionMgr["Session Manager"]:::mcp
    MCMng["Lifecycle Manager"]:::mcp
    MCPLB["MCP Load Balancer"]:::mcp
  end

  %% UI Layers
  subgraph "UI Layers"
    ConsoleUI["Console UI"]:::ui
    WebUI["Web UI"]:::ui
  end

  %% External Integrations
  subgraph "External Integrations"
    GitHub["GitHub Commands"]:::ext
    DockerDep["Docker Deployment"]:::ext
  end

  %% Connections
  CLI_bin -->|runs| Orchestrator
  CLI_src -->|invokes| Orchestrator

  Orchestrator -->|publishes events| EventBus
  EventBus -->|subscribes| Manager

  Manager -->|schedules| Scheduler
  Manager -->|coordinates| SwarmCoord
  Manager -->|balances| LoadBalancer
  Manager -->|messages| Messaging

  Manager -->|dispatches| SwarmIndex
  Manager -->|dispatches| Queen

  SwarmIndex -->|uses| Executor
  SwarmIndex -->|uses| ExecutorV2
  SwarmIndex -->|uses| DirectExec
  SwarmIndex -->|prompts| PromptMgr

  Queen -->|spawns| AgentCore
  AgentCore -->|communicates via| Comm
  AgentCore -->|monitors| MemMon
  AgentCore -->|manages DB| DBMgr
  AgentCore -->|registered by| AgentReg
  AgentCore -->|managed by| AgentMgr

  AgentCore -->|reads/writes| MemMgr
  AgentCore -->|reads/writes| Hivedb

  MemMgr -->|backend| SQLiteBE
  MemMgr -->|backend| MD_BE
  MemMgr -->|indexes| Indexer
  MemMgr -->|replicates| Replication

  ConsoleUI -->|subscribes to| EventBus
  WebUI -->|calls| MCPServer

  CLI_src -->|connects| MCPServer
  MCPServer -->|transport| HTTPTrans
  MCPServer -->|transport| SDTOTrans
  MCPServer -->|manages protocol| ProtocolMgr
  MCPServer -->|manages session| SessionMgr
  MCPServer -->|lifecycle| MCMng
  MCPServer -->|balances| MCPLB

  CLI_src -->|includes GitHub commands| GitHub
  DockerDep -->|deploys| Hivedb
  DockerDep -->|deploys| MCPServer

  %% Click Events
  click CLI_bin "https://github.com/ruvnet/claude-flow/tree/main/bin/claude-flow"
  click CLI_src "https://github.com/ruvnet/claude-flow/tree/main/src/cli"
  click EventBus "https://github.com/ruvnet/claude-flow/blob/main/src/core/event-bus.ts"
  click Orchestrator "https://github.com/ruvnet/claude-flow/blob/main/src/core/orchestrator.ts"
  click JSONPers "https://github.com/ruvnet/claude-flow/blob/main/src/core/json-persistence.ts"
  click Logger "https://github.com/ruvnet/claude-flow/blob/main/src/core/logger.ts"
  click Persistence "https://github.com/ruvnet/claude-flow/blob/main/src/core/persistence.ts"
  click Scheduler "https://github.com/ruvnet/claude-flow/blob/main/src/coordination/scheduler.ts"
  click SwarmCoord "https://github.com/ruvnet/claude-flow/blob/main/src/coordination/swarm-coordinator.ts"
  click LoadBalancer "https://github.com/ruvnet/claude-flow/blob/main/src/coordination/load-balancer.ts"
  click Messaging "https://github.com/ruvnet/claude-flow/blob/main/src/coordination/messaging.ts"
  click Manager "https://github.com/ruvnet/claude-flow/blob/main/src/coordination/manager.ts"
  click Queen "https://github.com/ruvnet/claude-flow/blob/main/src/hive-mind/core/Queen.ts"
  click AgentCore "https://github.com/ruvnet/claude-flow/blob/main/src/hive-mind/core/Agent.ts"
  click Comm "https://github.com/ruvnet/claude-flow/blob/main/src/hive-mind/core/Communication.ts"
  click MemMon "https://github.com/ruvnet/claude-flow/blob/main/src/hive-mind/core/MemoryMonitor.ts"
  click DBMgr "https://github.com/ruvnet/claude-flow/blob/main/src/hive-mind/core/DatabaseManager.ts"
  click AgentMgr "https://github.com/ruvnet/claude-flow/blob/main/src/agents/agent-manager.ts"
  click AgentReg "https://github.com/ruvnet/claude-flow/blob/main/src/agents/agent-registry.ts"
  click SwarmIndex "https://github.com/ruvnet/claude-flow/blob/main/src/swarm/index.ts"
  click Executor "https://github.com/ruvnet/claude-flow/blob/main/src/swarm/executor.ts"
  click ExecutorV2 "https://github.com/ruvnet/claude-flow/blob/main/src/swarm/executor-v2.ts"
  click DirectExec "https://github.com/ruvnet/claude-flow/blob/main/src/swarm/direct-executor.ts"
  click PromptMgr "https://github.com/ruvnet/claude-flow/blob/main/src/swarm/prompt-manager.ts"
  click SQLiteBE "https://github.com/ruvnet/claude-flow/blob/main/src/memory/backends/sqlite.ts"
  click MD_BE "https://github.com/ruvnet/claude-flow/blob/main/src/memory/backends/markdown.ts"
  click MemMgr "https://github.com/ruvnet/claude-flow/blob/main/src/memory/manager.ts"
  click Indexer "https://github.com/ruvnet/claude-flow/blob/main/src/memory/indexer.ts"
  click Replication "https://github.com/ruvnet/claude-flow/blob/main/src/memory/replication.ts"
  click Hivedb "https://github.com/ruvnet/claude-flow/blob/main/.hive-mind/hive.db"
  click MCPServer "https://github.com/ruvnet/claude-flow/blob/main/src/mcp/server.ts"
  click HTTPTrans "https://github.com/ruvnet/claude-flow/blob/main/src/mcp/transports/http.ts"
  click SDTOTrans "https://github.com/ruvnet/claude-flow/blob/main/src/mcp/transports/stdio.ts"
  click ProtocolMgr "https://github.com/ruvnet/claude-flow/blob/main/src/mcp/protocol-manager.ts"
  click SessionMgr "https://github.com/ruvnet/claude-flow/blob/main/src/mcp/session-manager.ts"
  click MCMng "https://github.com/ruvnet/claude-flow/blob/main/src/mcp/lifecycle-manager.ts"
  click MCPLB "https://github.com/ruvnet/claude-flow/blob/main/src/mcp/load-balancer.ts"
  click ConsoleUI "https://github.com/ruvnet/claude-flow/tree/main/src/ui/console/js"
  click WebUI "https://github.com/ruvnet/claude-flow/blob/main/src/ui/web-ui/core/EventBus.js"
  click GitHub "https://github.com/ruvnet/claude-flow/tree/main/src/cli/commands/github"
  click DockerDep "https://github.com/ruvnet/claude-flow/tree/main/infrastructure/docker"

  %% Styles
  classDef cli fill:#cfe2f3,stroke:#0366d6,stroke-width:1px
  classDef core fill:#d9ead3,stroke:#6aa84f,stroke-width:1px
  classDef coord fill:#d9ead3,stroke:#38761d,stroke-width:1px
  classDef agent fill:#f9cb9c,stroke:#e69138,stroke-width:1px
  classDef swarm fill:#f9cb9c,stroke:#b45f06,stroke-width:1px
  classDef mem fill:#ead1dc,stroke:#a64d79,stroke-width:1px
  classDef mcp fill:#fff2cc,stroke:#bf9000,stroke-width:1px
  classDef ui fill:#f4cccc,stroke:#cc0000,stroke-width:1px
  classDef ext fill:#e2e2e2,stroke:#888888,stroke-width:1px
```
