# solvent-labs-org/metaorcha architecture

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

- Interactive diagram: https://gitdiagram.com/solvent-labs-org/metaorcha
- Repository: https://github.com/solvent-labs-org/metaorcha

## Overview

Metaorcha is a multi-protocol agent harness: a user submits a goal, the platform discovers and plans agent work, executes it through protocol bridges, verifies the run, and presents structured results. The README documents the Registry → Planning & Discovery → SuperAgent path and the MCP, A2A, and computer-use bridges. The sampled execution middleware shows validation, payment, preflight, output normalization, and settlement responsibilities; the README documents the broader seven-step pipeline and CanvasKit rendering. Several subsystems are represented from documentation and the file tree because their implementation was not sampled.

Main entry points: [`services/superagent/src/superagent/middleware/pipeline.py`](https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/middleware/pipeline.py) (Call Middleware), [`services/superagent/src/superagent/api/routes.py`](https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/api/routes.py) (Run API), [`services/planning-discovery/src/planning_discovery/planning/pipeline.py`](https://github.com/solvent-labs-org/metaorcha/blob/main/services/planning-discovery/src/planning_discovery/planning/pipeline.py) (Plan And Resolve), [`frontend/src/App.tsx`](https://github.com/solvent-labs-org/metaorcha/blob/main/frontend/src/App.tsx) (Web Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interface"]
  node_frontend["Web Dashboard<br/>[App.tsx]"]
  node_api_client["API Client<br/>[client.ts]"]
end

subgraph group_platform["Gateway And Identity"]
  node_gateway_auth["Authentication<br/>[routes.py]"]
  node_gateway_sessions["Session Gateway<br/>[routes.py]"]
end

subgraph group_discovery["Agent Discovery"]
  node_registry[("Agent Registry<br/>[agents.py]")]
  node_planning_api["Planning API<br/>[planning.py]"]
  node_planning_pipeline["Plan And Resolve<br/>[pipeline.py]"]
  node_embedding_storage[("Agent Embeddings<br/>[storage.py]")]
end

subgraph group_execution["Run Execution"]
  node_superagent_api["Run API<br/>[routes.py]"]
  node_graph_runner["Workflow Runner<br/>[runner.py]"]
  node_agent_calls["Agent Call Execution"]
  node_middleware["Call Middleware<br/>[pipeline.py]"]
  node_mcp["MCP Bridge<br/>[mcp_handler.py]"]
  node_a2a["A2A Bridge<br/>[a2a_handler.py]"]
  node_computer_use["Computer Use Bridge"]
end

subgraph group_evidence["Verification And Output"]
  node_verification["Run Verification<br/>[attestation.py]"]
  node_audit["Evidence Package<br/>[audit.py]"]
  node_canvas["Canvas Renderer<br/>[CanvasRenderer.tsx]"]
end

node_user(("User"))
node_external_agents(("External Agents"))

node_user -->|"submits goal"| node_frontend
node_frontend -->|"requests API"| node_api_client
node_api_client -->|"authenticates"| node_gateway_auth
node_api_client -->|"sends session"| node_gateway_sessions
node_gateway_sessions -->|"forwards sessions"| node_superagent_api
node_registry -->|"supplies agents"| node_planning_pipeline
node_planning_api -->|"builds plan"| node_planning_pipeline
node_planning_pipeline -->|"resolves candidates"| node_embedding_storage
node_planning_pipeline -->|"provides workflow"| node_graph_runner
node_superagent_api -->|"runs turn"| node_graph_runner
node_graph_runner -->|"dispatches calls"| node_agent_calls
node_agent_calls -->|"runs call pipeline"| node_middleware
node_middleware -->|"dispatches protocol"| node_mcp
node_middleware -->|"dispatches protocol"| node_a2a
node_middleware -->|"dispatches protocol"| node_computer_use
node_mcp -->|"calls agents"| node_external_agents
node_a2a -->|"calls agents"| node_external_agents
node_computer_use -->|"operates systems"| node_external_agents
node_superagent_api -->|"seals run"| node_verification
node_superagent_api -->|"serves evidence"| node_audit
node_frontend -->|"renders dashboard"| node_canvas
node_middleware -.->|"settles calls"| node_external_agents

click node_frontend "https://github.com/solvent-labs-org/metaorcha/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/solvent-labs-org/metaorcha/blob/main/frontend/src/api/client.ts"
click node_gateway_auth "https://github.com/solvent-labs-org/metaorcha/blob/main/services/gateway/src/gateway/auth/routes.py"
click node_gateway_sessions "https://github.com/solvent-labs-org/metaorcha/blob/main/services/gateway/src/gateway/sessions/routes.py"
click node_registry "https://github.com/solvent-labs-org/metaorcha/blob/main/services/registry/src/api/v1/agents.py"
click node_planning_api "https://github.com/solvent-labs-org/metaorcha/blob/main/services/planning-discovery/src/planning_discovery/api/routes/planning.py"
click node_planning_pipeline "https://github.com/solvent-labs-org/metaorcha/blob/main/services/planning-discovery/src/planning_discovery/planning/pipeline.py"
click node_embedding_storage "https://github.com/solvent-labs-org/metaorcha/blob/main/services/planning-discovery/src/planning_discovery/manifest_processing/storage.py"
click node_superagent_api "https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/api/routes.py"
click node_graph_runner "https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/graph/runner.py"
click node_agent_calls "https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/nodes/execute_agent_calls.py"
click node_middleware "https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/middleware/pipeline.py"
click node_mcp "https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/handlers/mcp_handler.py"
click node_a2a "https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/handlers/a2a_handler.py"
click node_computer_use "https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/handlers/computer_use_handler.py"
click node_verification "https://github.com/solvent-labs-org/metaorcha/blob/main/services/validator/src/validator/attestation.py"
click node_audit "https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/api/audit.py"
click node_canvas "https://github.com/solvent-labs-org/metaorcha/blob/main/frontend/src/components/canvas/CanvasRenderer.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_frontend,node_api_client,node_user toneBlue
class node_gateway_auth,node_gateway_sessions toneAmber
class node_registry,node_planning_api,node_planning_pipeline,node_embedding_storage toneMint
class node_superagent_api,node_graph_runner,node_agent_calls,node_middleware,node_mcp,node_a2a,node_computer_use toneRose
class node_verification,node_audit,node_canvas,node_external_agents toneIndigo
```

## Components

### User Interface

- [Web Dashboard](https://github.com/solvent-labs-org/metaorcha/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API Client](https://github.com/solvent-labs-org/metaorcha/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Gateway And Identity

- [Authentication](https://github.com/solvent-labs-org/metaorcha/blob/main/services/gateway/src/gateway/auth/routes.py): `services/gateway/src/gateway/auth/routes.py`
- [Session Gateway](https://github.com/solvent-labs-org/metaorcha/blob/main/services/gateway/src/gateway/sessions/routes.py): `services/gateway/src/gateway/sessions/routes.py`

### Agent Discovery

- [Agent Registry](https://github.com/solvent-labs-org/metaorcha/blob/main/services/registry/src/api/v1/agents.py): `services/registry/src/api/v1/agents.py`
- [Planning API](https://github.com/solvent-labs-org/metaorcha/blob/main/services/planning-discovery/src/planning_discovery/api/routes/planning.py): `services/planning-discovery/src/planning_discovery/api/routes/planning.py`
- [Plan And Resolve](https://github.com/solvent-labs-org/metaorcha/blob/main/services/planning-discovery/src/planning_discovery/planning/pipeline.py): `services/planning-discovery/src/planning_discovery/planning/pipeline.py`
- [Agent Embeddings](https://github.com/solvent-labs-org/metaorcha/blob/main/services/planning-discovery/src/planning_discovery/manifest_processing/storage.py): `services/planning-discovery/src/planning_discovery/manifest_processing/storage.py`

### Run Execution

- [Run API](https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/api/routes.py): `services/superagent/src/superagent/api/routes.py`
- [Workflow Runner](https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/graph/runner.py): `services/superagent/src/superagent/graph/runner.py`
- [Agent Call Execution](https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/nodes/execute_agent_calls.py): `services/superagent/src/superagent/nodes/execute_agent_calls.py`
- [Call Middleware](https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/middleware/pipeline.py): `services/superagent/src/superagent/middleware/pipeline.py`
- [MCP Bridge](https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/handlers/mcp_handler.py): `services/superagent/src/superagent/handlers/mcp_handler.py`
- [A2A Bridge](https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/handlers/a2a_handler.py): `services/superagent/src/superagent/handlers/a2a_handler.py`
- [Computer Use Bridge](https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/handlers/computer_use_handler.py): `services/superagent/src/superagent/handlers/computer_use_handler.py`

### Verification And Output

- [Run Verification](https://github.com/solvent-labs-org/metaorcha/blob/main/services/validator/src/validator/attestation.py): `services/validator/src/validator/attestation.py`
- [Evidence Package](https://github.com/solvent-labs-org/metaorcha/blob/main/services/superagent/src/superagent/api/audit.py): `services/superagent/src/superagent/api/audit.py`
- [Canvas Renderer](https://github.com/solvent-labs-org/metaorcha/blob/main/frontend/src/components/canvas/CanvasRenderer.tsx): `frontend/src/components/canvas/CanvasRenderer.tsx`

### Other components

- **User**
- **External Agents**

## Connections

- User → Web Dashboard: submits goal (evidence: `README.md`)
- Web Dashboard → API Client: requests API
- API Client → Authentication: authenticates (evidence: `frontend/src/api/client.ts`)
- API Client → Session Gateway: sends session (evidence: `frontend/src/api/client.ts`)
- Session Gateway → Run API: forwards sessions (evidence: `services/gateway/src/gateway/sessions/routes.py`)
- Agent Registry → Plan And Resolve: supplies agents (evidence: `README.md`)
- Planning API → Plan And Resolve: builds plan
- Plan And Resolve → Agent Embeddings: resolves candidates (evidence: `services/planning-discovery/src/planning_discovery/planning/pipeline.py`)
- Plan And Resolve → Workflow Runner: provides workflow (evidence: `README.md`)
- Run API → Workflow Runner: runs turn (evidence: `services/superagent/src/superagent/api/routes.py`)
- Workflow Runner → Agent Call Execution: dispatches calls (evidence: `README.md`)
- Agent Call Execution → Call Middleware: runs call pipeline (evidence: `services/superagent/src/superagent/middleware/pipeline.py`)
- Call Middleware → MCP Bridge: dispatches protocol (evidence: `services/superagent/src/superagent/middleware/pipeline.py`)
- Call Middleware → A2A Bridge: dispatches protocol (evidence: `services/superagent/src/superagent/middleware/pipeline.py`)
- Call Middleware → Computer Use Bridge: dispatches protocol (evidence: `services/superagent/src/superagent/middleware/pipeline.py`)
- MCP Bridge → External Agents: calls agents (evidence: `README.md`)
- A2A Bridge → External Agents: calls agents (evidence: `README.md`)
- Computer Use Bridge → External Agents: operates systems (evidence: `README.md`)
- Run API → Run Verification: seals run (evidence: `services/superagent/src/superagent/api/routes.py`)
- Run API → Evidence Package: serves evidence (evidence: `services/superagent/src/superagent/api/routes.py`)
- Web Dashboard → Canvas Renderer: renders dashboard (evidence: `README.md`)
- Call Middleware → External Agents: settles calls
