# heddles/agent-orca architecture

> Architecture diagram of the GitHub repository heddles/agent-orca, 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/heddles/agent-orca
- Repository: https://github.com/heddles/agent-orca

## Overview

Agent ORCAstrator is a Kubernetes-native platform for defining, deploying, and running AI agents. Its principal workflow begins with an operator or integrator submitting an AgentRun or deploying an AgentDeployment; controllers assemble execution configuration and agent pods, while the model router handles inference and tool dispatch. Results and run state feed APIs and the UI for live execution, history, cost, and system views. The README documents additional workflow DAGs, RAG/KnowledgeBases, MCP, guardrails, and egress sinks. Edges reflect shown source references or README statements; unsampled internals are represented conservatively.

Main entry points: [`internal/controller/agentrun_controller.go`](https://github.com/heddles/agent-orca/blob/main/internal/controller/agentrun_controller.go) (Run reconciler), [`internal/router/router.go`](https://github.com/heddles/agent-orca/blob/main/internal/router/router.go) (Model router), [`api/v1alpha1/agent_types.go`](https://github.com/heddles/agent-orca/blob/main/api/v1alpha1/agent_types.go) (Agent resource types), [`internal/controller/agentdeployment_controller.go`](https://github.com/heddles/agent-orca/blob/main/internal/controller/agentdeployment_controller.go) (Deployment reconciler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Kubernetes control plane"]
  node_crds["Agent resource types<br/>[agent_types.go]"]
  node_agent_controller["Agent controller"]
  node_deployment_controller["Deployment reconciler"]
  node_run_controller["Run reconciler"]
  node_workflow_controller["Workflow reconciler"]
  node_webhook["Run validation"]
end

subgraph group_execution["Agent execution"]
  node_pod_builder["Agent pod builder<br/>[builder.go]"]
  node_model_router["Model router<br/>[router.go]"]
  node_executor["Tool executor<br/>[executor.go]"]
  node_model_process["Model router service<br/>[main.go]"]
end

subgraph group_knowledge["Knowledge and integrations"]
  node_kb_controller["Knowledge controller"]
  node_rag["RAG pipeline<br/>[pipeline.go]"]
  node_qdrant[("Vector store<br/>[qdrant.go]")]
  node_mcp["MCP client<br/>[client.go]"]
  node_ingester["MCP ingester<br/>[main.go]"]
end

subgraph group_interfaces["APIs and interfaces"]
  node_api_server["Operator APIs<br/>[apiserver.go]"]
  node_ui_proxy["UI proxy<br/>[main.go]"]
  node_ui["Operations UI<br/>[main.tsx]"]
  node_sse_client["API and streams<br/>[sse.ts]"]
  node_aoctl["aoctl CLI<br/>[main.go]"]
end

subgraph group_persistence["State and results"]
  node_checkpoint[("Run checkpoints<br/>[store.go]")]
  node_state_store[("Conversation state<br/>[store.go]")]
  node_run_archive[("Run archive<br/>[store.go]")]
  node_egress["Result delivery<br/>[egress.go]"]
end

node_operator(("Operator"))
node_integrator(("API integrator"))
node_external_model{{"LLM provider"}}
node_external_sink{{"Configured sink"}}

node_operator -->|"defines resources"| node_crds
node_crds -.->|"configures"| node_deployment_controller
node_crds -.->|"configures"| node_run_controller
node_crds -.->|"configures"| node_workflow_controller
node_crds -.->|"configures"| node_kb_controller
node_run_controller -->|"builds pod"| node_pod_builder
node_deployment_controller -->|"builds deployment"| node_pod_builder
node_run_controller -->|"configures routing"| node_model_router
node_deployment_controller -->|"configures routing"| node_model_router
node_run_controller -->|"configures state"| node_state_store
node_run_controller -->|"archives runs"| node_run_archive
node_run_controller -->|"publishes results"| node_egress
node_run_controller -->|"resolves tools"| node_mcp
node_deployment_controller -->|"resolves tools"| node_mcp
node_model_process -->|"starts router"| node_model_router
node_model_process -->|"creates store"| node_state_store
node_model_process -->|"binds executor"| node_executor
node_model_router -->|"dispatches tools"| node_executor
node_model_router -->|"uses state"| node_state_store
node_model_router -->|"calls MCP tools"| node_mcp
node_model_router -.->|"requests inference"| node_external_model
node_kb_controller -->|"uses RAG"| node_rag
node_ingester -->|"discovers documents"| node_mcp
node_ingester -->|"chunks and embeds"| node_rag
node_rag -.->|"stores vectors"| node_qdrant
node_operator -->|"views operations"| node_ui
node_ui -->|"requests UI APIs"| node_ui_proxy
node_ui -->|"renders live views"| node_sse_client
node_sse_client -.->|"fetches and streams"| node_api_server
node_integrator -->|"submits tasks"| node_aoctl
node_aoctl -.->|"calls task APIs"| node_api_server
node_integrator -->|"submits tasks"| node_api_server
node_egress -.->|"delivers results"| node_external_sink
node_run_controller -.->|"supports checkpoints"| node_checkpoint

click node_crds "https://github.com/heddles/agent-orca/blob/main/api/v1alpha1/agent_types.go"
click node_agent_controller "https://github.com/heddles/agent-orca/blob/main/internal/controller/agent_controller.go"
click node_deployment_controller "https://github.com/heddles/agent-orca/blob/main/internal/controller/agentdeployment_controller.go"
click node_run_controller "https://github.com/heddles/agent-orca/blob/main/internal/controller/agentrun_controller.go"
click node_workflow_controller "https://github.com/heddles/agent-orca/blob/main/internal/controller/agentworkflow_controller.go"
click node_kb_controller "https://github.com/heddles/agent-orca/blob/main/internal/controller/knowledgebase_controller.go"
click node_webhook "https://github.com/heddles/agent-orca/blob/main/internal/webhook/agentrun_webhook.go"
click node_pod_builder "https://github.com/heddles/agent-orca/blob/main/internal/podbuilder/builder.go"
click node_model_router "https://github.com/heddles/agent-orca/blob/main/internal/router/router.go"
click node_executor "https://github.com/heddles/agent-orca/blob/main/internal/executor/executor.go"
click node_checkpoint "https://github.com/heddles/agent-orca/blob/main/internal/checkpoint/store.go"
click node_state_store "https://github.com/heddles/agent-orca/blob/main/internal/state/store.go"
click node_run_archive "https://github.com/heddles/agent-orca/blob/main/internal/postgresql/store.go"
click node_egress "https://github.com/heddles/agent-orca/blob/main/internal/egress/egress.go"
click node_rag "https://github.com/heddles/agent-orca/blob/main/internal/rag/pipeline.go"
click node_qdrant "https://github.com/heddles/agent-orca/blob/main/internal/rag/qdrant.go"
click node_mcp "https://github.com/heddles/agent-orca/blob/main/internal/mcp/client.go"
click node_api_server "https://github.com/heddles/agent-orca/blob/main/internal/apiserver/apiserver.go"
click node_ui_proxy "https://github.com/heddles/agent-orca/blob/main/cmd/ui-proxy/main.go"
click node_ui "https://github.com/heddles/agent-orca/blob/main/ui/src/main.tsx"
click node_sse_client "https://github.com/heddles/agent-orca/blob/main/ui/src/api/sse.ts"
click node_aoctl "https://github.com/heddles/agent-orca/blob/main/cmd/aoctl/main.go"
click node_model_process "https://github.com/heddles/agent-orca/blob/main/cmd/model-router/main.go"
click node_ingester "https://github.com/heddles/agent-orca/blob/main/cmd/mcp-ingester/main.go"

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_crds,node_agent_controller,node_deployment_controller,node_run_controller,node_workflow_controller,node_webhook toneBlue
class node_pod_builder,node_model_router,node_executor,node_model_process toneAmber
class node_kb_controller,node_rag,node_qdrant,node_mcp,node_ingester,node_integrator toneMint
class node_api_server,node_ui_proxy,node_ui,node_sse_client,node_aoctl toneRose
class node_checkpoint,node_state_store,node_run_archive,node_egress,node_operator,node_external_model,node_external_sink toneIndigo
```

## Components

### Kubernetes control plane

- [Agent resource types](https://github.com/heddles/agent-orca/blob/main/api/v1alpha1/agent_types.go): `api/v1alpha1/agent_types.go`
- [Agent controller](https://github.com/heddles/agent-orca/blob/main/internal/controller/agent_controller.go): `internal/controller/agent_controller.go`
- [Deployment reconciler](https://github.com/heddles/agent-orca/blob/main/internal/controller/agentdeployment_controller.go): `internal/controller/agentdeployment_controller.go`
- [Run reconciler](https://github.com/heddles/agent-orca/blob/main/internal/controller/agentrun_controller.go): `internal/controller/agentrun_controller.go`
- [Workflow reconciler](https://github.com/heddles/agent-orca/blob/main/internal/controller/agentworkflow_controller.go): `internal/controller/agentworkflow_controller.go`
- [Run validation](https://github.com/heddles/agent-orca/blob/main/internal/webhook/agentrun_webhook.go): `internal/webhook/agentrun_webhook.go`

### Agent execution

- [Agent pod builder](https://github.com/heddles/agent-orca/blob/main/internal/podbuilder/builder.go): `internal/podbuilder/builder.go`
- [Model router](https://github.com/heddles/agent-orca/blob/main/internal/router/router.go): `internal/router/router.go`
- [Tool executor](https://github.com/heddles/agent-orca/blob/main/internal/executor/executor.go): `internal/executor/executor.go`
- [Model router service](https://github.com/heddles/agent-orca/blob/main/cmd/model-router/main.go): `cmd/model-router/main.go`

### Knowledge and integrations

- [Knowledge controller](https://github.com/heddles/agent-orca/blob/main/internal/controller/knowledgebase_controller.go): `internal/controller/knowledgebase_controller.go`
- [RAG pipeline](https://github.com/heddles/agent-orca/blob/main/internal/rag/pipeline.go): `internal/rag/pipeline.go`
- [Vector store](https://github.com/heddles/agent-orca/blob/main/internal/rag/qdrant.go): `internal/rag/qdrant.go`
- [MCP client](https://github.com/heddles/agent-orca/blob/main/internal/mcp/client.go): `internal/mcp/client.go`
- [MCP ingester](https://github.com/heddles/agent-orca/blob/main/cmd/mcp-ingester/main.go): `cmd/mcp-ingester/main.go`

### APIs and interfaces

- [Operator APIs](https://github.com/heddles/agent-orca/blob/main/internal/apiserver/apiserver.go): `internal/apiserver/apiserver.go`
- [UI proxy](https://github.com/heddles/agent-orca/blob/main/cmd/ui-proxy/main.go): `cmd/ui-proxy/main.go`
- [Operations UI](https://github.com/heddles/agent-orca/blob/main/ui/src/main.tsx): `ui/src/main.tsx`
- [API and streams](https://github.com/heddles/agent-orca/blob/main/ui/src/api/sse.ts): `ui/src/api/sse.ts`
- [aoctl CLI](https://github.com/heddles/agent-orca/blob/main/cmd/aoctl/main.go): `cmd/aoctl/main.go`

### State and results

- [Run checkpoints](https://github.com/heddles/agent-orca/blob/main/internal/checkpoint/store.go): `internal/checkpoint/store.go`
- [Conversation state](https://github.com/heddles/agent-orca/blob/main/internal/state/store.go): `internal/state/store.go`
- [Run archive](https://github.com/heddles/agent-orca/blob/main/internal/postgresql/store.go): `internal/postgresql/store.go`
- [Result delivery](https://github.com/heddles/agent-orca/blob/main/internal/egress/egress.go): `internal/egress/egress.go`

### Other components

- **Operator**
- **API integrator**
- **LLM provider**
- **Configured sink**

## Connections

- Operator → Agent resource types: defines resources (evidence: `README.md`)
- Agent resource types → Deployment reconciler: configures
- Agent resource types → Run reconciler: configures
- Agent resource types → Workflow reconciler: configures
- Agent resource types → Knowledge controller: configures
- Run reconciler → Agent pod builder: builds pod (evidence: `internal/controller/agentrun_controller.go`)
- Deployment reconciler → Agent pod builder: builds deployment (evidence: `internal/controller/agentdeployment_controller.go`)
- Run reconciler → Model router: configures routing (evidence: `internal/controller/agentrun_controller.go`)
- Deployment reconciler → Model router: configures routing (evidence: `internal/controller/agentdeployment_controller.go`)
- Run reconciler → Conversation state: configures state (evidence: `internal/controller/agentrun_controller.go`)
- Run reconciler → Run archive: archives runs (evidence: `internal/controller/agentrun_controller.go`)
- Run reconciler → Result delivery: publishes results (evidence: `internal/controller/agentrun_controller.go`)
- Run reconciler → MCP client: resolves tools (evidence: `internal/controller/agentrun_controller.go`)
- Deployment reconciler → MCP client: resolves tools (evidence: `internal/controller/agentdeployment_controller.go`)
- Model router service → Model router: starts router (evidence: `cmd/model-router/main.go`)
- Model router service → Conversation state: creates store (evidence: `cmd/model-router/main.go`)
- Model router service → Tool executor: binds executor (evidence: `cmd/model-router/main.go`)
- Model router → Tool executor: dispatches tools (evidence: `internal/router/router.go`)
- Model router → Conversation state: uses state (evidence: `internal/router/router.go`)
- Model router → MCP client: calls MCP tools (evidence: `internal/router/router.go`)
- Model router → LLM provider: requests inference
- Knowledge controller → RAG pipeline: uses RAG (evidence: `internal/controller/knowledgebase_controller.go`)
- MCP ingester → MCP client: discovers documents (evidence: `cmd/mcp-ingester/main.go`)
- MCP ingester → RAG pipeline: chunks and embeds (evidence: `cmd/mcp-ingester/main.go`)
- RAG pipeline → Vector store: stores vectors
- Operator → Operations UI: views operations (evidence: `README.md`)
- Operations UI → UI proxy: requests UI APIs (evidence: `README.md`)
- Operations UI → API and streams: renders live views (evidence: `ui/src/main.tsx`)
- API and streams → Operator APIs: fetches and streams
- API integrator → aoctl CLI: submits tasks (evidence: `README.md`)
- aoctl CLI → Operator APIs: calls task APIs
- API integrator → Operator APIs: submits tasks (evidence: `README.md`)
- Result delivery → Configured sink: delivers results
- Run reconciler → Run checkpoints: supports checkpoints
