# kocoro-lab/shannon architecture

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

- Interactive diagram: https://gitdiagram.com/kocoro-lab/shannon
- Repository: https://github.com/kocoro-lab/shannon

## Overview

Shannon is a production multi-agent platform: clients submit tasks through a Go gateway, which routes them into Temporal-backed orchestration and agent execution; results and execution events return to clients. The workflow includes complexity/decomposition routing, strategy-specific execution, tool/LLM calls, and result synthesis. Major documented branches include research, swarm, approval, budgets, sessions, schedules, and streaming. Paths for unsampled capabilities use exact enclosing directories; wiring is included only where the README or sampled source supports it.

Main entry points: [`go/orchestrator/internal/workflows/orchestrator_router.go`](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/workflows/orchestrator_router.go) (Workflow router), [`go/orchestrator/internal/streaming/manager.go`](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/streaming/manager.go) (Event streaming), [`rust/agent-core/src/lib.rs`](https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/src/lib.rs) (Agent core), [`python/llm-service/llm_service/tools/registry.py`](https://github.com/kocoro-lab/shannon/blob/main/python/llm-service/llm_service/tools/registry.py) (Agent loop and tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client access"]
  node_clients["SDK and desktop<br/>[client.py]"]
  node_desktop["Desktop interface<br/>[page.tsx]"]
end

subgraph group_control["Gateway and control"]
  node_gateway["Go gateway<br/>[main.go]"]
  node_taskapi["Task API<br/>[task.go]"]
  node_orchestrator["Workflow router"]
  node_strategies["Execution strategies"]
  node_research["Research workflow<br/>[research.go]"]
  node_swarm["Swarm workflow<br/>[swarm_workflow.go]"]
end

subgraph group_execution["Agent execution"]
  node_agentcore["Agent core<br/>[lib.rs]"]
  node_llmapi["LLM service API<br/>[agent.py]"]
  node_agentloop["Agent loop and tools<br/>[registry.py]"]
  node_providers["Provider manager<br/>[manager.py]"]
  node_browser["Browser automation<br/>[app.py]"]
end

subgraph group_state["State and governance"]
  node_stream["Event streaming<br/>[manager.go]"]
  node_sessions["Session continuity<br/>[manager.go]"]
  node_budget["Token budgets<br/>[manager.go]"]
  node_policy["Policy and approvals<br/>[engine.go]"]
  node_schedules["Scheduled tasks<br/>[manager.go]"]
end

subgraph group_integrations["External services"]
  node_postgres[("PostgreSQL<br/>[client.go]")]
  node_redis[("Redis<br/>[manager.go]")]
  node_temporal["Temporal"]
  node_llmproviders["LLM providers"]
  node_toolservices["Tool services"]
end

node_user(("Task user"))

node_user -->|"submits task"| node_clients
node_user -->|"submits task"| node_desktop
node_clients -->|"calls REST"| node_gateway
node_desktop -->|"calls API"| node_gateway
node_gateway -->|"dispatches request"| node_taskapi
node_taskapi -->|"starts workflow"| node_orchestrator
node_orchestrator -->|"routes task"| node_strategies
node_orchestrator -->|"routes research"| node_research
node_orchestrator -->|"routes swarm"| node_swarm
node_strategies -->|"executes agents"| node_agentcore
node_research -->|"runs research"| node_agentcore
node_swarm -->|"coordinates agents"| node_agentcore
node_agentcore -->|"requests inference"| node_llmapi
node_llmapi -->|"runs agent"| node_agentloop
node_agentloop -->|"requests completion"| node_providers
node_providers -->|"calls provider"| node_llmproviders
node_agentloop -->|"invokes tools"| node_toolservices
node_toolservices -.->|"uses browser"| node_browser
node_orchestrator -->|"runs workflows"| node_temporal
node_orchestrator -->|"tracks budget"| node_budget
node_orchestrator -->|"checks policy"| node_policy
node_orchestrator -->|"uses session"| node_sessions
node_orchestrator -->|"emits events"| node_stream
node_stream -->|"publishes events"| node_redis
node_stream -->|"persists events"| node_postgres
node_schedules -->|"creates schedules"| node_temporal
node_schedules -->|"persists schedules"| node_postgres
node_sessions -->|"stores sessions"| node_redis
node_stream -->|"streams events"| node_clients
node_stream -->|"streams events"| node_desktop

click node_clients "https://github.com/kocoro-lab/shannon/blob/main/clients/python/src/shannon/client.py"
click node_gateway "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/cmd/gateway/main.go"
click node_taskapi "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/cmd/gateway/internal/handlers/task.go"
click node_orchestrator "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/workflows/orchestrator_router.go"
click node_strategies "https://github.com/kocoro-lab/shannon/tree/main/go/orchestrator/internal/workflows/strategies"
click node_research "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/workflows/strategies/research.go"
click node_swarm "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/workflows/swarm_workflow.go"
click node_agentcore "https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/src/lib.rs"
click node_llmapi "https://github.com/kocoro-lab/shannon/blob/main/python/llm-service/llm_service/api/agent.py"
click node_agentloop "https://github.com/kocoro-lab/shannon/blob/main/python/llm-service/llm_service/tools/registry.py"
click node_providers "https://github.com/kocoro-lab/shannon/blob/main/python/llm-service/llm_provider/manager.py"
click node_browser "https://github.com/kocoro-lab/shannon/blob/main/python/playwright-service/app.py"
click node_stream "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/streaming/manager.go"
click node_sessions "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/session/manager.go"
click node_budget "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/budget/manager.go"
click node_policy "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/policy/engine.go"
click node_schedules "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/schedules/manager.go"
click node_postgres "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/db/client.go"
click node_redis "https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/streaming/manager.go"
click node_toolservices "https://github.com/kocoro-lab/shannon/tree/main/python/llm-service/llm_service/tools/builtin"
click node_desktop "https://github.com/kocoro-lab/shannon/blob/main/desktop/app/(app)/runs/page.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_clients,node_desktop toneBlue
class node_gateway,node_taskapi,node_orchestrator,node_strategies,node_research,node_swarm toneAmber
class node_agentcore,node_llmapi,node_agentloop,node_providers,node_browser toneMint
class node_stream,node_sessions,node_budget,node_policy,node_schedules,node_user toneRose
class node_postgres,node_redis,node_temporal,node_llmproviders,node_toolservices toneIndigo
```

## Components

### Client access

- [SDK and desktop](https://github.com/kocoro-lab/shannon/blob/main/clients/python/src/shannon/client.py): `clients/python/src/shannon/client.py`
- [Desktop interface](https://github.com/kocoro-lab/shannon/blob/main/desktop/app/(app)/runs/page.tsx): `desktop/app/(app)/runs/page.tsx`

### Gateway and control

- [Go gateway](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/cmd/gateway/main.go): `go/orchestrator/cmd/gateway/main.go`
- [Task API](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/cmd/gateway/internal/handlers/task.go): `go/orchestrator/cmd/gateway/internal/handlers/task.go`
- [Workflow router](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/workflows/orchestrator_router.go): `go/orchestrator/internal/workflows/orchestrator_router.go`
- [Execution strategies](https://github.com/kocoro-lab/shannon/tree/main/go/orchestrator/internal/workflows/strategies): `go/orchestrator/internal/workflows/strategies`
- [Research workflow](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/workflows/strategies/research.go): `go/orchestrator/internal/workflows/strategies/research.go`
- [Swarm workflow](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/workflows/swarm_workflow.go): `go/orchestrator/internal/workflows/swarm_workflow.go`

### Agent execution

- [Agent core](https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/src/lib.rs): `rust/agent-core/src/lib.rs`
- [LLM service API](https://github.com/kocoro-lab/shannon/blob/main/python/llm-service/llm_service/api/agent.py): `python/llm-service/llm_service/api/agent.py`
- [Agent loop and tools](https://github.com/kocoro-lab/shannon/blob/main/python/llm-service/llm_service/tools/registry.py): `python/llm-service/llm_service/tools/registry.py`
- [Provider manager](https://github.com/kocoro-lab/shannon/blob/main/python/llm-service/llm_provider/manager.py): `python/llm-service/llm_provider/manager.py`
- [Browser automation](https://github.com/kocoro-lab/shannon/blob/main/python/playwright-service/app.py): `python/playwright-service/app.py`

### State and governance

- [Event streaming](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/streaming/manager.go): `go/orchestrator/internal/streaming/manager.go`
- [Session continuity](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/session/manager.go): `go/orchestrator/internal/session/manager.go`
- [Token budgets](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/budget/manager.go): `go/orchestrator/internal/budget/manager.go`
- [Policy and approvals](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/policy/engine.go): `go/orchestrator/internal/policy/engine.go`
- [Scheduled tasks](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/schedules/manager.go): `go/orchestrator/internal/schedules/manager.go`

### External services

- [PostgreSQL](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/db/client.go): `go/orchestrator/internal/db/client.go`
- [Redis](https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/internal/streaming/manager.go): `go/orchestrator/internal/streaming/manager.go`
- **Temporal**
- **LLM providers**
- [Tool services](https://github.com/kocoro-lab/shannon/tree/main/python/llm-service/llm_service/tools/builtin): `python/llm-service/llm_service/tools/builtin`

### Other components

- **Task user**

## Connections

- Task user → SDK and desktop: submits task
- Task user → Desktop interface: submits task
- SDK and desktop → Go gateway: calls REST
- Desktop interface → Go gateway: calls API
- Go gateway → Task API: dispatches request
- Task API → Workflow router: starts workflow
- Workflow router → Execution strategies: routes task
- Workflow router → Research workflow: routes research
- Workflow router → Swarm workflow: routes swarm
- Execution strategies → Agent core: executes agents
- Research workflow → Agent core: runs research
- Swarm workflow → Agent core: coordinates agents
- Agent core → LLM service API: requests inference
- LLM service API → Agent loop and tools: runs agent
- Agent loop and tools → Provider manager: requests completion
- Provider manager → LLM providers: calls provider
- Agent loop and tools → Tool services: invokes tools
- Tool services → Browser automation: uses browser
- Workflow router → Temporal: runs workflows
- Workflow router → Token budgets: tracks budget
- Workflow router → Policy and approvals: checks policy
- Workflow router → Session continuity: uses session
- Workflow router → Event streaming: emits events
- Event streaming → Redis: publishes events
- Event streaming → PostgreSQL: persists events
- Scheduled tasks → Temporal: creates schedules
- Scheduled tasks → PostgreSQL: persists schedules
- Session continuity → Redis: stores sessions
- Event streaming → SDK and desktop: streams events
- Event streaming → Desktop interface: streams events