# csergey/ruflo architecture

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

- Interactive diagram: https://gitdiagram.com/csergey/ruflo
- Repository: https://github.com/csergey/ruflo

## Overview

Ruflo is an agent-orchestration harness for Claude Code and Codex: users submit work through its CLI or MCP interface, which routes tasks into coordinated agents that use memory and LLM providers; learning feeds successful patterns back into later work. The repository also contains a chat-oriented RuVocal UI, federation and graph-intelligence capabilities, and a goal-planning UI. The README documents the high-level orchestration flow; sampled source confirms MCP session handling, workflow execution, federation policy, and graph-reasoning components. Several core modules are indexed but unsampled, so their detailed internal calls are not inferred.

Main entry points: [`v3/@claude-flow/cli/src/commands`](https://github.com/csergey/ruflo/tree/main/v3/%40claude-flow/cli/src/commands) (Specialist Agents), [`v3/mcp/server.ts`](https://github.com/csergey/ruflo/blob/main/v3/mcp/server.ts) (MCP Server), [`v3/src/coordination/application/SwarmCoordinator.ts`](https://github.com/csergey/ruflo/blob/main/v3/src/coordination/application/SwarmCoordinator.ts) (Swarm Coordinator), [`v3/@claude-flow/memory/src/controller-registry.ts`](https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/memory/src/controller-registry.ts) (Agent Memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_cli["Ruflo CLI<br/>[cli.js]"]
  node_mcp["MCP Server<br/>[server.ts]"]
  node_sessions["MCP Sessions<br/>[session-manager.ts]"]
end

subgraph group_orchestration["Agent Orchestration"]
  node_router["Task Router<br/>[route.ts]"]
  node_swarm["Swarm Coordinator"]
  node_workflow["Workflow Engine<br/>[WorkflowEngine.ts]"]
  node_agents["Specialist Agents"]
  node_providers["LLM Providers"]
end

subgraph group_learning["Memory And Learning"]
  node_memory[("Agent Memory")]
  node_learning_loop["Learning Loop<br/>[intelligence.ts]"]
  node_embeddings["Embedding Service"]
end

subgraph group_extensions["Federation And Intelligence"]
  node_federation_policy["Federation Policy<br/>[policy-engine.ts]"]
  node_pii["PII Protection"]
  node_graph["Graph Reasoning<br/>[solver-bridge.ts]"]
  node_signed_artifact["Signed Artifacts<br/>[signed-artifact.ts]"]
end

subgraph group_interfaces["Product Interfaces"]
  node_chat_ui["RuVocal Chat<br/>[+page.svelte]"]
  node_chat_api["Conversation API<br/>[+server.ts]"]
  node_chat_generation["Text Generation<br/>[generate.ts]"]
  node_goal_ui["Goal Planner UI<br/>[App.tsx]"]
end

node_user(("User"))

node_user -->|"submits tasks"| node_cli
node_cli -.->|"routes work"| node_router
node_user -->|"sends requests"| node_mcp
node_mcp -->|"manages sessions"| node_sessions
node_mcp -.->|"dispatches tools"| node_router
node_router -->|"coordinates agents"| node_swarm
node_swarm -.->|"executes workflows"| node_workflow
node_swarm -->|"dispatches tasks"| node_agents
node_agents -->|"requests inference"| node_providers
node_agents -->|"uses memory"| node_memory
node_memory -->|"informs learning"| node_learning_loop
node_learning_loop -->|"improves patterns"| node_agents
node_memory -.->|"retrieves vectors"| node_embeddings
node_user -.->|"chats"| node_chat_ui
node_chat_ui -.->|"requests conversations"| node_chat_api
node_chat_api -.->|"generates replies"| node_chat_generation
node_user -.->|"plans goals"| node_goal_ui
node_federation_policy -->|"uses PII policy"| node_pii
node_graph -.->|"produces evidence"| node_signed_artifact

click node_cli "https://github.com/csergey/ruflo/blob/main/bin/cli.js"
click node_mcp "https://github.com/csergey/ruflo/blob/main/v3/mcp/server.ts"
click node_sessions "https://github.com/csergey/ruflo/blob/main/v3/mcp/session-manager.ts"
click node_router "https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/cli/src/commands/route.ts"
click node_swarm "https://github.com/csergey/ruflo/blob/main/v3/src/coordination/application/SwarmCoordinator.ts"
click node_workflow "https://github.com/csergey/ruflo/blob/main/v3/src/task-execution/application/WorkflowEngine.ts"
click node_agents "https://github.com/csergey/ruflo/tree/main/v3/%40claude-flow/cli/src/commands"
click node_providers "https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/providers/src/provider-manager.ts"
click node_memory "https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/memory/src/controller-registry.ts"
click node_learning_loop "https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/cli/src/memory/intelligence.ts"
click node_embeddings "https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/embeddings/src/embedding-service.ts"
click node_federation_policy "https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/plugin-agent-federation/src/application/policy-engine.ts"
click node_pii "https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/plugin-agent-federation/src/domain/services/pii-pipeline-service.ts"
click node_graph "https://github.com/csergey/ruflo/blob/main/plugins/ruflo-graph-intelligence/src/infrastructure/solver-bridge.ts"
click node_signed_artifact "https://github.com/csergey/ruflo/blob/main/plugins/ruflo-graph-intelligence/src/domain/signed-artifact.ts"
click node_chat_ui "https://github.com/csergey/ruflo/blob/main/ruflo/src/ruvocal/src/routes/%2Bpage.svelte"
click node_chat_api "https://github.com/csergey/ruflo/blob/main/ruflo/src/ruvocal/src/routes/conversation/%2Bserver.ts"
click node_chat_generation "https://github.com/csergey/ruflo/blob/main/ruflo/src/ruvocal/src/lib/server/textGeneration/generate.ts"
click node_goal_ui "https://github.com/csergey/ruflo/blob/main/v3/goal_ui/src/App.tsx"

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_mcp,node_sessions,node_user toneBlue
class node_router,node_swarm,node_workflow,node_agents,node_providers toneAmber
class node_memory,node_learning_loop,node_embeddings toneMint
class node_federation_policy,node_pii,node_graph,node_signed_artifact toneRose
class node_chat_ui,node_chat_api,node_chat_generation,node_goal_ui toneIndigo
```

## Components

### User Entry

- [Ruflo CLI](https://github.com/csergey/ruflo/blob/main/bin/cli.js): `bin/cli.js`
- [MCP Server](https://github.com/csergey/ruflo/blob/main/v3/mcp/server.ts): `v3/mcp/server.ts`
- [MCP Sessions](https://github.com/csergey/ruflo/blob/main/v3/mcp/session-manager.ts): `v3/mcp/session-manager.ts`

### Agent Orchestration

- [Task Router](https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/cli/src/commands/route.ts): `v3/@claude-flow/cli/src/commands/route.ts`
- [Swarm Coordinator](https://github.com/csergey/ruflo/blob/main/v3/src/coordination/application/SwarmCoordinator.ts): `v3/src/coordination/application/SwarmCoordinator.ts`
- [Workflow Engine](https://github.com/csergey/ruflo/blob/main/v3/src/task-execution/application/WorkflowEngine.ts): `v3/src/task-execution/application/WorkflowEngine.ts`
- [Specialist Agents](https://github.com/csergey/ruflo/tree/main/v3/%40claude-flow/cli/src/commands): `v3/@claude-flow/cli/src/commands`
- [LLM Providers](https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/providers/src/provider-manager.ts): `v3/@claude-flow/providers/src/provider-manager.ts`

### Memory And Learning

- [Agent Memory](https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/memory/src/controller-registry.ts): `v3/@claude-flow/memory/src/controller-registry.ts`
- [Learning Loop](https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/cli/src/memory/intelligence.ts): `v3/@claude-flow/cli/src/memory/intelligence.ts`
- [Embedding Service](https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/embeddings/src/embedding-service.ts): `v3/@claude-flow/embeddings/src/embedding-service.ts`

### Federation And Intelligence

- [Federation Policy](https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/plugin-agent-federation/src/application/policy-engine.ts): `v3/@claude-flow/plugin-agent-federation/src/application/policy-engine.ts`
- [PII Protection](https://github.com/csergey/ruflo/blob/main/v3/%40claude-flow/plugin-agent-federation/src/domain/services/pii-pipeline-service.ts): `v3/@claude-flow/plugin-agent-federation/src/domain/services/pii-pipeline-service.ts`
- [Graph Reasoning](https://github.com/csergey/ruflo/blob/main/plugins/ruflo-graph-intelligence/src/infrastructure/solver-bridge.ts): `plugins/ruflo-graph-intelligence/src/infrastructure/solver-bridge.ts`
- [Signed Artifacts](https://github.com/csergey/ruflo/blob/main/plugins/ruflo-graph-intelligence/src/domain/signed-artifact.ts): `plugins/ruflo-graph-intelligence/src/domain/signed-artifact.ts`

### Product Interfaces

- [RuVocal Chat](https://github.com/csergey/ruflo/blob/main/ruflo/src/ruvocal/src/routes/%2Bpage.svelte): `ruflo/src/ruvocal/src/routes/+page.svelte`
- [Conversation API](https://github.com/csergey/ruflo/blob/main/ruflo/src/ruvocal/src/routes/conversation/%2Bserver.ts): `ruflo/src/ruvocal/src/routes/conversation/+server.ts`
- [Text Generation](https://github.com/csergey/ruflo/blob/main/ruflo/src/ruvocal/src/lib/server/textGeneration/generate.ts): `ruflo/src/ruvocal/src/lib/server/textGeneration/generate.ts`
- [Goal Planner UI](https://github.com/csergey/ruflo/blob/main/v3/goal_ui/src/App.tsx): `v3/goal_ui/src/App.tsx`

### Other components

- **User**

## Connections

- User → Ruflo CLI: submits tasks (evidence: `README.md`)
- Ruflo CLI → Task Router: routes work
- User → MCP Server: sends requests (evidence: `README.md`)
- MCP Server → MCP Sessions: manages sessions (evidence: `v3/mcp/server.ts`)
- MCP Server → Task Router: dispatches tools
- Task Router → Swarm Coordinator: coordinates agents (evidence: `README.md`)
- Swarm Coordinator → Workflow Engine: executes workflows (evidence: `v3/src/task-execution/application/WorkflowEngine.ts`)
- Swarm Coordinator → Specialist Agents: dispatches tasks (evidence: `README.md`)
- Specialist Agents → LLM Providers: requests inference (evidence: `README.md`)
- Specialist Agents → Agent Memory: uses memory (evidence: `README.md`)
- Agent Memory → Learning Loop: informs learning (evidence: `README.md`)
- Learning Loop → Specialist Agents: improves patterns (evidence: `README.md`)
- Agent Memory → Embedding Service: retrieves vectors
- User → RuVocal Chat: chats
- RuVocal Chat → Conversation API: requests conversations
- Conversation API → Text Generation: generates replies
- User → Goal Planner UI: plans goals
- Federation Policy → PII Protection: uses PII policy (evidence: `v3/@claude-flow/plugin-agent-federation/src/application/policy-engine.ts`)
- Graph Reasoning → Signed Artifacts: produces evidence