# hfdaraijan/ruflo architecture

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

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

## Overview

Ruflo is an agent harness for Claude Code and Codex: it routes work, coordinates agents, supplies memory and tools, and applies security controls. The principal documented flow runs from a CLI/MCP or editor interaction through routing and swarm coordination to agent work, with learning and memory supporting later tasks. The graph combines that documented flow with source-backed workflow, embedding, policy, federation, and UI components. Several links reflect README-level architecture because their implementation was not sampled.

Main entry points: [`plugins`](https://github.com/hfdaraijan/ruflo/tree/main/plugins) (Specialist agents), [`ruflo/src/ruvocal/src/lib/server/textGeneration/generate.ts`](https://github.com/hfdaraijan/ruflo/blob/main/ruflo/src/ruvocal/src/lib/server/textGeneration/generate.ts) (UI API), [`v3/@claude-flow/cli/src/ruvector/coverage-router.ts`](https://github.com/hfdaraijan/ruflo/blob/main/v3/%40claude-flow/cli/src/ruvector/coverage-router.ts) (Task router), [`ruflo/bin/ruflo.js`](https://github.com/hfdaraijan/ruflo/blob/main/ruflo/bin/ruflo.js) (Ruflo CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["Ruflo CLI<br/>[ruflo.js]"]
  node_mcp["MCP bridge<br/>[index.js]"]
  node_hooks["Hooks<br/>[ruflo-hook.cjs]"]
end

subgraph group_coordination["Coordination"]
  node_router["Task router<br/>[coverage-router.ts]"]
  node_workflow["Workflow engine<br/>[WorkflowEngine.ts]"]
  node_swarm["Swarm coordination"]
  node_agents["Specialist agents"]
end

subgraph group_intelligence["Agent capabilities"]
  node_learning["Learning loop"]
  node_embeddings["Embedding service"]
  node_memory[("Agent memory")]
  node_llm["LLM providers"]
end

subgraph group_governance["Safety and federation"]
  node_policy["Policy engine<br/>[engine.ts]"]
  node_federation["Federation policy<br/>[policy-engine.ts]"]
  node_pii["PII pipeline"]
end

subgraph group_surfaces["User surfaces"]
  node_ui["Ruflo UI<br/>[+page.svelte]"]
  node_uiapi["UI API<br/>[generate.ts]"]
  node_db[("Conversation store<br/>[database.ts]")]
end

node_engineer(("Engineer"))
node_claude["Claude Code / Codex"]

node_engineer -->|"invokes"| node_cli
node_claude -->|"triggers"| node_hooks
node_claude -->|"calls tools"| node_mcp
node_cli -->|"routes work"| node_router
node_hooks -->|"routes work"| node_router
node_mcp -->|"dispatches"| node_swarm
node_router -->|"dispatches"| node_swarm
node_swarm -->|"coordinates"| node_agents
node_workflow -->|"executes tasks"| node_agents
node_agents -->|"feeds outcomes"| node_learning
node_learning -->|"updates patterns"| node_memory
node_agents -->|"uses memory"| node_memory
node_agents -->|"requests inference"| node_llm
node_agents -->|"checks actions"| node_policy
node_federation -->|"applies filtering"| node_pii
node_engineer -->|"uses"| node_ui
node_ui -->|"sends requests"| node_uiapi
node_uiapi -->|"reads/writes"| node_db
node_uiapi -->|"requests generation"| node_llm

click node_cli "https://github.com/hfdaraijan/ruflo/blob/main/ruflo/bin/ruflo.js"
click node_mcp "https://github.com/hfdaraijan/ruflo/blob/main/ruflo/src/mcp-bridge/index.js"
click node_hooks "https://github.com/hfdaraijan/ruflo/blob/main/plugin/scripts/ruflo-hook.cjs"
click node_router "https://github.com/hfdaraijan/ruflo/blob/main/v3/%40claude-flow/cli/src/ruvector/coverage-router.ts"
click node_workflow "https://github.com/hfdaraijan/ruflo/blob/main/v3/src/task-execution/application/WorkflowEngine.ts"
click node_swarm "https://github.com/hfdaraijan/ruflo/tree/main/plugins"
click node_agents "https://github.com/hfdaraijan/ruflo/tree/main/plugins"
click node_learning "https://github.com/hfdaraijan/ruflo/tree/main/plugins/ruflo-metaharness/scripts"
click node_embeddings "https://github.com/hfdaraijan/ruflo/blob/main/v3/%40claude-flow/embeddings/src/embedding-service.ts"
click node_memory "https://github.com/hfdaraijan/ruflo/tree/main/plugins"
click node_policy "https://github.com/hfdaraijan/ruflo/blob/main/v3/%40claude-flow/security/src/policy/engine.ts"
click node_federation "https://github.com/hfdaraijan/ruflo/blob/main/v3/%40claude-flow/plugin-agent-federation/src/application/policy-engine.ts"
click node_pii "https://github.com/hfdaraijan/ruflo/blob/main/v3/%40claude-flow/plugin-agent-federation/src/domain/services/pii-pipeline-service.ts"
click node_ui "https://github.com/hfdaraijan/ruflo/blob/main/ruflo/src/ruvocal/src/routes/%2Bpage.svelte"
click node_uiapi "https://github.com/hfdaraijan/ruflo/blob/main/ruflo/src/ruvocal/src/lib/server/textGeneration/generate.ts"
click node_db "https://github.com/hfdaraijan/ruflo/blob/main/ruflo/src/ruvocal/src/lib/server/database.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_mcp,node_hooks toneBlue
class node_router,node_workflow,node_swarm,node_agents toneAmber
class node_learning,node_embeddings,node_memory,node_llm toneMint
class node_policy,node_federation,node_pii toneRose
class node_ui,node_uiapi,node_db,node_engineer,node_claude toneIndigo
```

## Components

### Entry points

- [Ruflo CLI](https://github.com/hfdaraijan/ruflo/blob/main/ruflo/bin/ruflo.js): `ruflo/bin/ruflo.js`
- [MCP bridge](https://github.com/hfdaraijan/ruflo/blob/main/ruflo/src/mcp-bridge/index.js): `ruflo/src/mcp-bridge/index.js`
- [Hooks](https://github.com/hfdaraijan/ruflo/blob/main/plugin/scripts/ruflo-hook.cjs): `plugin/scripts/ruflo-hook.cjs`

### Coordination

- [Task router](https://github.com/hfdaraijan/ruflo/blob/main/v3/%40claude-flow/cli/src/ruvector/coverage-router.ts): `v3/@claude-flow/cli/src/ruvector/coverage-router.ts`
- [Workflow engine](https://github.com/hfdaraijan/ruflo/blob/main/v3/src/task-execution/application/WorkflowEngine.ts): `v3/src/task-execution/application/WorkflowEngine.ts`
- [Swarm coordination](https://github.com/hfdaraijan/ruflo/tree/main/plugins): `plugins`
- [Specialist agents](https://github.com/hfdaraijan/ruflo/tree/main/plugins): `plugins`

### Agent capabilities

- [Learning loop](https://github.com/hfdaraijan/ruflo/tree/main/plugins/ruflo-metaharness/scripts): `plugins/ruflo-metaharness/scripts`
- [Embedding service](https://github.com/hfdaraijan/ruflo/blob/main/v3/%40claude-flow/embeddings/src/embedding-service.ts): `v3/@claude-flow/embeddings/src/embedding-service.ts`
- [Agent memory](https://github.com/hfdaraijan/ruflo/tree/main/plugins): `plugins`
- **LLM providers**

### Safety and federation

- [Policy engine](https://github.com/hfdaraijan/ruflo/blob/main/v3/%40claude-flow/security/src/policy/engine.ts): `v3/@claude-flow/security/src/policy/engine.ts`
- [Federation policy](https://github.com/hfdaraijan/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 pipeline](https://github.com/hfdaraijan/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`

### User surfaces

- [Ruflo UI](https://github.com/hfdaraijan/ruflo/blob/main/ruflo/src/ruvocal/src/routes/%2Bpage.svelte): `ruflo/src/ruvocal/src/routes/+page.svelte`
- [UI API](https://github.com/hfdaraijan/ruflo/blob/main/ruflo/src/ruvocal/src/lib/server/textGeneration/generate.ts): `ruflo/src/ruvocal/src/lib/server/textGeneration/generate.ts`
- [Conversation store](https://github.com/hfdaraijan/ruflo/blob/main/ruflo/src/ruvocal/src/lib/server/database.ts): `ruflo/src/ruvocal/src/lib/server/database.ts`

### Other components

- **Engineer**
- **Claude Code / Codex**

## Connections

- Engineer → Ruflo CLI: invokes
- Claude Code / Codex → Hooks: triggers
- Claude Code / Codex → MCP bridge: calls tools
- Ruflo CLI → Task router: routes work
- Hooks → Task router: routes work
- MCP bridge → Swarm coordination: dispatches
- Task router → Swarm coordination: dispatches
- Swarm coordination → Specialist agents: coordinates
- Workflow engine → Specialist agents: executes tasks
- Specialist agents → Learning loop: feeds outcomes
- Learning loop → Agent memory: updates patterns
- Specialist agents → Agent memory: uses memory
- Specialist agents → LLM providers: requests inference
- Specialist agents → Policy engine: checks actions
- Federation policy → PII pipeline: applies filtering
- Engineer → Ruflo UI: uses
- Ruflo UI → UI API: sends requests
- UI API → Conversation store: reads/writes
- UI API → LLM providers: requests generation