# agentwrapper/agent-orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/agentwrapper/agent-orchestrator
- Repository: https://github.com/agentwrapper/agent-orchestrator

## Overview

Agent Orchestrator is a local workspace for planning, running, and supervising coding-agent tasks through review and merge. The main workflow is to choose a project and task, launch an agent in an isolated workspace, follow its session and changes, then inspect its pull request and review status on the Kanban. Project-level orchestration delegates focused work to workers. The graph reflects documented capabilities and sampled call paths; some subsystem wiring is not shown because its source was not sampled.

Main entry points: [`backend/internal/session_manager/manager.go`](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/session_manager/manager.go) (Session manager), [`frontend/src/renderer/hooks/useWorkspaceQuery.ts`](https://github.com/agentwrapper/agent-orchestrator/blob/main/frontend/src/renderer/hooks/useWorkspaceQuery.ts) (Workspace queries), [`backend/internal/domain/kanban.go`](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/domain/kanban.go) (Kanban state), [`cloud/internal/httpapi/workspace_review_handlers.go`](https://github.com/agentwrapper/agent-orchestrator/blob/main/cloud/internal/httpapi/workspace_review_handlers.go) (Workspace review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Workspace interface"]
  node_workspace_ui["Workspace queries"]
end

subgraph group_session["Session execution"]
  node_http_api["HTTP API<br/>[api.go]"]
  node_controllers["Session controllers<br/>[sessions.go]"]
  node_manager["Session manager<br/>[manager.go]"]
  node_workspace["Workspace providers<br/>[router.go]"]
  node_runtime["Terminal runtime<br/>[runtimeselect.go]"]
  node_chat["Chat controller<br/>[controller.go]"]
  node_lifecycle["Session lifecycle<br/>[manager.go]"]
end

subgraph group_agents["Agent integration"]
  node_agent_registry["Agent registry<br/>[registry.go]"]
  node_chat_drivers["Chat drivers<br/>[registry.go]"]
end

subgraph group_coordination["Planning and tracking"]
  node_orchestrator["Project orchestrator<br/>[orchestrator.go]"]
  node_worker_api["Worker coordination"]
  node_kanban["Kanban state<br/>[kanban.go]"]
  node_review_api["Workspace review"]
end

subgraph group_external["Source control"]
  node_scm["SCM providers<br/>[provider.go]"]
  node_tracker["Issue trackers<br/>[tracker.go]"]
end

node_user(("Desktop user"))
node_github(("GitHub"))
node_gitlab(("GitLab"))

node_user -->|"uses"| node_workspace_ui
node_workspace_ui -->|"requests workspace data"| node_http_api
node_http_api -->|"routes requests"| node_controllers
node_controllers -->|"manages sessions"| node_manager
node_manager -->|"creates workspaces"| node_workspace
node_manager -->|"starts runtime"| node_runtime
node_manager -->|"resolves agents"| node_agent_registry
node_manager -->|"controls chat sessions"| node_chat
node_chat -->|"uses chat driver"| node_chat_drivers
node_manager -->|"updates lifecycle"| node_lifecycle
node_user -->|"plans work"| node_orchestrator
node_orchestrator -->|"delegates workers"| node_worker_api
node_worker_api -->|"contributes session state"| node_kanban
node_workspace_ui -->|"displays board"| node_kanban
node_review_api -->|"dispatches workspace review"| node_workspace
node_review_api -->|"publishes workspace changes"| node_kanban
node_scm -->|"connects"| node_github
node_scm -->|"connects"| node_gitlab
node_tracker -.->|"connects"| node_github
node_tracker -.->|"connects"| node_gitlab

click node_workspace_ui "https://github.com/agentwrapper/agent-orchestrator/blob/main/frontend/src/renderer/hooks/useWorkspaceQuery.ts"
click node_http_api "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/httpd/api.go"
click node_controllers "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/httpd/controllers/sessions.go"
click node_manager "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/session_manager/manager.go"
click node_workspace "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/workspace/router/router.go"
click node_runtime "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/runtime/runtimeselect/runtimeselect.go"
click node_chat "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/service/chat/controller.go"
click node_lifecycle "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/lifecycle/manager.go"
click node_agent_registry "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/agent/registry/registry.go"
click node_chat_drivers "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/chatdriver/registry/registry.go"
click node_orchestrator "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/cli/orchestrator.go"
click node_worker_api "https://github.com/agentwrapper/agent-orchestrator/blob/main/cloud/internal/httpapi/worker_orchestration_handlers.go"
click node_kanban "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/domain/kanban.go"
click node_review_api "https://github.com/agentwrapper/agent-orchestrator/blob/main/cloud/internal/httpapi/workspace_review_handlers.go"
click node_scm "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/scm/multi/provider.go"
click node_tracker "https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/tracker/multi/tracker.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_workspace_ui,node_user toneBlue
class node_http_api,node_controllers,node_manager,node_workspace,node_runtime,node_chat,node_lifecycle toneAmber
class node_agent_registry,node_chat_drivers toneMint
class node_orchestrator,node_worker_api,node_kanban,node_review_api toneRose
class node_scm,node_tracker,node_github,node_gitlab toneIndigo
```

## Components

### Workspace interface

- [Workspace queries](https://github.com/agentwrapper/agent-orchestrator/blob/main/frontend/src/renderer/hooks/useWorkspaceQuery.ts): `frontend/src/renderer/hooks/useWorkspaceQuery.ts`

### Session execution

- [HTTP API](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/httpd/api.go): `backend/internal/httpd/api.go`
- [Session controllers](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/httpd/controllers/sessions.go): `backend/internal/httpd/controllers/sessions.go`
- [Session manager](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/session_manager/manager.go): `backend/internal/session_manager/manager.go`
- [Workspace providers](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/workspace/router/router.go): `backend/internal/adapters/workspace/router/router.go`
- [Terminal runtime](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/runtime/runtimeselect/runtimeselect.go): `backend/internal/adapters/runtime/runtimeselect/runtimeselect.go`
- [Chat controller](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/service/chat/controller.go): `backend/internal/service/chat/controller.go`
- [Session lifecycle](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/lifecycle/manager.go): `backend/internal/lifecycle/manager.go`

### Agent integration

- [Agent registry](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/agent/registry/registry.go): `backend/internal/adapters/agent/registry/registry.go`
- [Chat drivers](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/chatdriver/registry/registry.go): `backend/internal/adapters/chatdriver/registry/registry.go`

### Planning and tracking

- [Project orchestrator](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/cli/orchestrator.go): `backend/internal/cli/orchestrator.go`
- [Worker coordination](https://github.com/agentwrapper/agent-orchestrator/blob/main/cloud/internal/httpapi/worker_orchestration_handlers.go): `cloud/internal/httpapi/worker_orchestration_handlers.go`
- [Kanban state](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/domain/kanban.go): `backend/internal/domain/kanban.go`
- [Workspace review](https://github.com/agentwrapper/agent-orchestrator/blob/main/cloud/internal/httpapi/workspace_review_handlers.go): `cloud/internal/httpapi/workspace_review_handlers.go`

### Source control

- [SCM providers](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/scm/multi/provider.go): `backend/internal/adapters/scm/multi/provider.go`
- [Issue trackers](https://github.com/agentwrapper/agent-orchestrator/blob/main/backend/internal/adapters/tracker/multi/tracker.go): `backend/internal/adapters/tracker/multi/tracker.go`

### Other components

- **Desktop user**
- **GitHub**
- **GitLab**

## Connections

- Desktop user → Workspace queries: uses
- Workspace queries → HTTP API: requests workspace data
- HTTP API → Session controllers: routes requests
- Session controllers → Session manager: manages sessions
- Session manager → Workspace providers: creates workspaces
- Session manager → Terminal runtime: starts runtime
- Session manager → Agent registry: resolves agents
- Session manager → Chat controller: controls chat sessions
- Chat controller → Chat drivers: uses chat driver
- Session manager → Session lifecycle: updates lifecycle
- Desktop user → Project orchestrator: plans work
- Project orchestrator → Worker coordination: delegates workers
- Worker coordination → Kanban state: contributes session state
- Workspace queries → Kanban state: displays board
- Workspace review → Workspace providers: dispatches workspace review
- Workspace review → Kanban state: publishes workspace changes
- SCM providers → GitHub: connects
- SCM providers → GitLab: connects
- Issue trackers → GitHub: connects
- Issue trackers → GitLab: connects