# fcn06/swarm architecture

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

- Interactive diagram: https://gitdiagram.com/fcn06/swarm
- Repository: https://github.com/fcn06/swarm

## Overview

Swarm’s visible runtime is centered on multi-agent planning and execution: a client request reaches a planner, which creates or loads a workflow and sends it to an executor; the executor runs graph activities through agent, task, or tool invokers. Separate modules provide basic agents and MCP-based context and tool handling. The README also describes gateway, resilience, discovery, and evaluation capabilities, but gateway implementation paths are absent from the supplied tree; those branches are therefore not mapped. Edges reflect excerpted calls or explicit README statements, not inferred wiring.

Main entry points: [`planner_agent/src/business_logic/planner_agent.rs`](https://github.com/fcn06/swarm/blob/main/planner_agent/src/business_logic/planner_agent.rs) (Planner Agent), [`workflow_management/src/graph/graph_orchestrator.rs`](https://github.com/fcn06/swarm/blob/main/workflow_management/src/graph/graph_orchestrator.rs) (Graph Orchestrator), [`mcp_runtime/src/mcp_agent_logic/agent.rs`](https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_agent_logic/agent.rs) (MCP Agent), [`mcp_runtime/src/mcp_client/mcp_client.rs`](https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_client/mcp_client.rs) (MCP Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Planning"]
  node_planner["Planner Agent<br/>[planner_agent.rs]"]
end

subgraph group_execution["Workflow Execution"]
  node_workflow["Graph Orchestrator"]
  node_conditions["Condition Evaluator"]
  node_agent_invoker["Agent Invoker<br/>[agent_invoker.rs]"]
  node_task_invoker["Task Invoker<br/>[task_invoker.rs]"]
  node_tool_invoker["Tool Invoker<br/>[tool_invoker.rs]"]
  node_astar["A-star Planner<br/>[a_star.rs]"]
end

subgraph group_agents["Agent Runtime"]
  node_executor["Executor Agent<br/>[executor_agent.rs]"]
  node_basic_agent["Basic Agent<br/>[basic_agent.rs]"]
  node_factory["Agent Factory<br/>[agent_factory.rs]"]
end

subgraph group_mcp["MCP Runtime"]
  node_mcp_agent["MCP Agent<br/>[agent.rs]"]
  node_context["Context Providers"]
  node_response["Response Processing"]
  node_mcp_client["MCP Client<br/>[mcp_client.rs]"]
  node_mcp_tools["Tool Conversion<br/>[tools.rs]"]
  node_mcp_runtime["MCP Runtime<br/>[mcp_runtime.rs]"]
end

node_client(("Workflow Client"))
node_llm{{"LLM Provider"}}
node_memory[("Memory Service")]
node_mcp_server{{"MCP Server"}}
node_discovery{{"Discovery Service"}}
node_evaluation{{"Evaluation Service"}}

node_client -->|"submits request"| node_planner
node_planner -->|"requests plan"| node_llm
node_planner -->|"sends task"| node_executor
node_planner -.->|"queries capabilities"| node_discovery
node_planner -.->|"evaluates outcome"| node_evaluation
node_executor -.->|"executes graph"| node_workflow
node_workflow -->|"evaluates conditions"| node_conditions
node_workflow -->|"delegates agent work"| node_agent_invoker
node_workflow -->|"invokes tasks"| node_task_invoker
node_workflow -->|"invokes tools"| node_tool_invoker
node_mcp_agent -->|"calls tools"| node_mcp_client
node_mcp_agent -->|"formats tools"| node_mcp_tools
node_mcp_agent -.->|"assembles context"| node_context
node_context -->|"reads history and facts"| node_memory
node_mcp_runtime -->|"initializes client"| node_mcp_client
node_mcp_client -->|"connects over HTTP"| node_mcp_server
node_mcp_agent -.->|"processes response"| node_response

click node_client "https://github.com/fcn06/swarm/blob/main/planner_agent/bin/simple_workflow_agent_client.rs"
click node_planner "https://github.com/fcn06/swarm/blob/main/planner_agent/src/business_logic/planner_agent.rs"
click node_executor "https://github.com/fcn06/swarm/blob/main/executor_agent/src/business_logic/executor_agent.rs"
click node_workflow "https://github.com/fcn06/swarm/blob/main/workflow_management/src/graph/graph_orchestrator.rs"
click node_conditions "https://github.com/fcn06/swarm/blob/main/workflow_management/src/tasks/condition_evaluator.rs"
click node_agent_invoker "https://github.com/fcn06/swarm/blob/main/workflow_management/src/agent_communication/agent_invoker.rs"
click node_task_invoker "https://github.com/fcn06/swarm/blob/main/workflow_management/src/tasks/task_invoker.rs"
click node_tool_invoker "https://github.com/fcn06/swarm/blob/main/workflow_management/src/tools/tool_invoker.rs"
click node_astar "https://github.com/fcn06/swarm/blob/main/workflow_management/src/graph/a_star.rs"
click node_basic_agent "https://github.com/fcn06/swarm/blob/main/basic_agent/src/business_logic/basic_agent.rs"
click node_factory "https://github.com/fcn06/swarm/blob/main/agent_factory/src/agent_factory.rs"
click node_mcp_agent "https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_agent_logic/agent.rs"
click node_context "https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_agent_logic/context_providers.rs"
click node_response "https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_agent_logic/process_response.rs"
click node_mcp_client "https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_client/mcp_client.rs"
click node_mcp_tools "https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_tools/tools.rs"
click node_mcp_runtime "https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/runtime/mcp_runtime.rs"

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_planner,node_client toneBlue
class node_workflow,node_conditions,node_agent_invoker,node_task_invoker,node_tool_invoker,node_astar,node_memory toneAmber
class node_executor,node_basic_agent,node_factory,node_mcp_server toneMint
class node_mcp_agent,node_context,node_response,node_mcp_client,node_mcp_tools,node_mcp_runtime toneRose
class node_llm,node_discovery,node_evaluation toneIndigo
```

## Components

### Planning

- [Planner Agent](https://github.com/fcn06/swarm/blob/main/planner_agent/src/business_logic/planner_agent.rs): `planner_agent/src/business_logic/planner_agent.rs`

### Workflow Execution

- [Graph Orchestrator](https://github.com/fcn06/swarm/blob/main/workflow_management/src/graph/graph_orchestrator.rs): `workflow_management/src/graph/graph_orchestrator.rs`
- [Condition Evaluator](https://github.com/fcn06/swarm/blob/main/workflow_management/src/tasks/condition_evaluator.rs): `workflow_management/src/tasks/condition_evaluator.rs`
- [Agent Invoker](https://github.com/fcn06/swarm/blob/main/workflow_management/src/agent_communication/agent_invoker.rs): `workflow_management/src/agent_communication/agent_invoker.rs`
- [Task Invoker](https://github.com/fcn06/swarm/blob/main/workflow_management/src/tasks/task_invoker.rs): `workflow_management/src/tasks/task_invoker.rs`
- [Tool Invoker](https://github.com/fcn06/swarm/blob/main/workflow_management/src/tools/tool_invoker.rs): `workflow_management/src/tools/tool_invoker.rs`
- [A-star Planner](https://github.com/fcn06/swarm/blob/main/workflow_management/src/graph/a_star.rs): `workflow_management/src/graph/a_star.rs`

### Agent Runtime

- [Executor Agent](https://github.com/fcn06/swarm/blob/main/executor_agent/src/business_logic/executor_agent.rs): `executor_agent/src/business_logic/executor_agent.rs`
- [Basic Agent](https://github.com/fcn06/swarm/blob/main/basic_agent/src/business_logic/basic_agent.rs): `basic_agent/src/business_logic/basic_agent.rs`
- [Agent Factory](https://github.com/fcn06/swarm/blob/main/agent_factory/src/agent_factory.rs): `agent_factory/src/agent_factory.rs`

### MCP Runtime

- [MCP Agent](https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_agent_logic/agent.rs): `mcp_runtime/src/mcp_agent_logic/agent.rs`
- [Context Providers](https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_agent_logic/context_providers.rs): `mcp_runtime/src/mcp_agent_logic/context_providers.rs`
- [Response Processing](https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_agent_logic/process_response.rs): `mcp_runtime/src/mcp_agent_logic/process_response.rs`
- [MCP Client](https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_client/mcp_client.rs): `mcp_runtime/src/mcp_client/mcp_client.rs`
- [Tool Conversion](https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/mcp_tools/tools.rs): `mcp_runtime/src/mcp_tools/tools.rs`
- [MCP Runtime](https://github.com/fcn06/swarm/blob/main/mcp_runtime/src/runtime/mcp_runtime.rs): `mcp_runtime/src/runtime/mcp_runtime.rs`

### Other components

- [Workflow Client](https://github.com/fcn06/swarm/blob/main/planner_agent/bin/simple_workflow_agent_client.rs): `planner_agent/bin/simple_workflow_agent_client.rs`
- **LLM Provider**
- **Memory Service**
- **MCP Server**
- **Discovery Service**
- **Evaluation Service**

## Connections

- Workflow Client → Planner Agent: submits request (evidence: `planner_agent/bin/simple_workflow_agent_client.rs`)
- Planner Agent → LLM Provider: requests plan (evidence: `planner_agent/src/business_logic/planner_agent.rs`)
- Planner Agent → Executor Agent: sends task (evidence: `planner_agent/src/business_logic/planner_agent.rs`)
- Planner Agent → Discovery Service: queries capabilities
- Planner Agent → Evaluation Service: evaluates outcome
- Executor Agent → Graph Orchestrator: executes graph
- Graph Orchestrator → Condition Evaluator: evaluates conditions (evidence: `workflow_management/src/graph/graph_orchestrator.rs`)
- Graph Orchestrator → Agent Invoker: delegates agent work (evidence: `workflow_management/src/graph/graph_orchestrator.rs`)
- Graph Orchestrator → Task Invoker: invokes tasks (evidence: `workflow_management/src/graph/graph_orchestrator.rs`)
- Graph Orchestrator → Tool Invoker: invokes tools (evidence: `workflow_management/src/graph/graph_orchestrator.rs`)
- MCP Agent → MCP Client: calls tools (evidence: `mcp_runtime/src/mcp_agent_logic/agent.rs`)
- MCP Agent → Tool Conversion: formats tools (evidence: `mcp_runtime/src/mcp_agent_logic/agent.rs`)
- MCP Agent → Context Providers: assembles context
- Context Providers → Memory Service: reads history and facts (evidence: `mcp_runtime/src/mcp_agent_logic/context_providers.rs`)
- MCP Runtime → MCP Client: initializes client (evidence: `mcp_runtime/src/runtime/mcp_runtime.rs`)
- MCP Client → MCP Server: connects over HTTP (evidence: `mcp_runtime/src/mcp_client/mcp_client.rs`)
- MCP Agent → Response Processing: processes response
