# swarmclawai/swarmclaw architecture

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

- Interactive diagram: https://gitdiagram.com/swarmclawai/swarmclaw
- Repository: https://github.com/swarmclawai/swarmclaw

## Overview

1. **Overall shape**
   SwarmClaw is a self-hosted, full-stack TypeScript control plane for autonomous agents. The same codebase serves three entrypoints: the Next.js dashboard/API, a Node CLI (`swarmclaw`), and an Electron desktop shell. Most behavior is implemented in shared server-side libraries so the UI, CLI, and desktop app all drive the same runtime.

2. **Primary UI surface**
   The dashboard lives under `src/app` and uses Next.js App Router pages plus server route handlers. The UI is organized by domain: agents, chats, tasks, runs, schedules, memory, providers, connectors, skills, protocols, quality, missions, chatrooms, and settings. Components and feature modules mostly stay thin and call into shared query/client helpers rather than implementing business logic themselves.

3. **API layer as the control plane**
   The `src/app/api/**/route.ts` tree is the main inbound API surface. It exposes CRUD and action endpoints for nearly every domain, plus special routes for health, auth, uploads/files, sharing, exports/imports, A2A discovery, OpenClaw, SwarmDock, SwarmFeed, MCP servers, and quality gates. These routes translate HTTP into domain services in `src/lib/server/**`.

4. **Server-side domain services**
   The real architecture lives in `src/lib/server`. It is split into repositories, services, schedulers, and execution engines for each domain: agents, chats, tasks, runs, protocols, schedules, memory, connectors, gateways, skills, extensions, credentials, wallets, projects, and more. The pattern is consistent: route handlers call services, services call repositories and runtime helpers, and repositories isolate persistence details.

5. **Agent/chat execution pipeline**
   The core runtime path is chat execution. `src/lib/server/chat-execution/**` and `src/lib/server/agents/**` handle prompt construction, tool routing, stream execution, turn finalization, continuation, compaction, and state tracking. This is where agent turns become model calls, tool events, persisted messages, follow-up actions, and connector deliveries. The chat UI is essentially a live view over this pipeline.

6. **Autonomy and background work**
   Long-running behavior is handled by the runtime layer under `src/lib/server/runtime/**` and adjacent autonomy modules. This includes heartbeat loops, wake scheduling, queueing, orphan recovery, daemon control, estop/guardrails, scheduled-run preflight, and session-run management. The runtime is what turns agents from interactive chat participants into autonomous workers that can resume, retry, and recover after interruption.

7. **Orchestration primitives**
   SwarmClaw supports structured execution beyond simple chat: tasks, runs, protocols, missions, schedules, and structured sessions. `src/lib/server/protocols/**` models DAG-style flows with branches, joins, loops, subflows, and swarms; `tasks` and `runs` provide durable execution records and handoff packets; `schedules` triggers work over time; `missions` wraps operational workflows with budgets and reports. This is the orchestration boundary diagrammatically: user intent enters, and one of these durable work primitives executes it.

8. **Provider and gateway abstraction**
   Model access is abstracted through `src/lib/providers/**` and `src/lib/server/provider*`. The system supports both API providers and CLI-backed providers, plus OpenAI-compatible endpoints, local runtimes like Ollama, and OpenClaw gateways. Provider health, model discovery, diagnostics, and per-agent provider config are first-class because provider choice materially changes how execution streams, tool use, and context limits behave.

9. **External integrations**
   Connectors are a major boundary: `src/lib/server/connectors/**` and the related UI/API manage Slack, Discord, Telegram, WhatsApp, Teams, Matrix, email, file queues, OpenClaw, SwarmDock, and SwarmFeed. The connector subsystem includes inbound delivery, outbound outboxes, pairing/access, policy checks, media handling, and connector-specific runtime state. It is effectively the event bridge between SwarmClaw and outside communication channels.

10. **Memory, knowledge, and artifacts**
   Durable context is handled by the memory and knowledge subsystems plus documents/artifacts. `src/lib/server/memory/**` manages tiers, graph/retrieval, dreams/reflection, consolidation, and session memory scope; `knowledge` handles sources and hygiene; `artifacts`, `documents`, and `files` expose persisted outputs and shared references. This is the long-term persistence boundary for agent learning and operator recall, separate from transient chat transcripts.

11. **Skills, extensions, and tool surfaces**
   Agent capabilities are assembled from skills, MCP servers, built-in tools, and extensions. `src/lib/server/session-tools/**` builds the per-session tool set, while `skills`, `extensions`, and `mcp-*` modules manage discovery, install/update, conformance, approvals, and managed resources. This is the capability layer that determines what an agent can actually do in a turn.

12. **Persistence and local runtime model**
   The repo is designed around a local data directory and workspace model rather than a remote central database. Repositories under `src/lib/server/*-repository.ts` persist durable records for chats, agents, tasks, schedules, memory, connectors, shares, and configs, while runtime helpers create task/session workspaces and file-backed snapshots where needed. The architecture is therefore “local control plane with durable state,” not a stateless API server.

13. **Desktop, CLI, and deployment wrappers**
   `bin/`, `src/cli`, and `electron/` wrap the same application into different operating modes. The CLI exposes operational commands for setup, diagnostics, updates, schedules, tasks, runs, providers, and gateways. Electron manages the desktop shell, server lifecycle, updater, and app paths. Container and hosted deploy files (`Dockerfile`, `docker-compose.yml`, `fly.toml`, `railway.json`, `render.yaml`) all point to the same core runtime.

14. **Observability, quality, and release safety**
   Quality and observability are not sidecars; they are built into the product. `src/lib/server/observability`, `src/lib/server/quality`, `src/lib/server/eval`, and the `/quality` APIs provide architecture-health checks, release-readiness scoring, eval gating, and trace export. This creates an operator feedback loop around the runtime so execution, provider health, and autonomy can be inspected and gated before release.

15. **Key architectural boundary**
   The clearest diagram boundary is between the interactive shell layer and the durable runtime layer. UI pages, CLI commands, and Electron all converge on the same API routes and shared server libraries; those server libraries then fan out to provider adapters, connector bridges, storage repositories, and runtime workers. That shared-control-plane design is the central architectural idea of the repository.

Main entry points: [`src/lib/server`](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server) (Server libs), [`src/lib/server/chat-execution`](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/chat-execution) (Chat engine), [`src/lib/server/runtime`](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/runtime) (Autonomy runtime), [`src/app/api`](https://github.com/swarmclawai/swarmclaw/tree/main/src/app/api) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry points"]
  node_dashboard["Dashboard<br/>Next.js app"]
  node_cli["CLI<br/>node command"]
  node_electron["Desktop shell<br/>Electron app"]
end

subgraph group_controlplane["Control plane"]
  node_api["API routes<br/>HTTP control plane"]
  node_server["Server libs<br/>domain services"]
end

subgraph group_runtime["Runtime"]
  node_chat["Chat engine<br/>execution pipeline"]
  node_agents["Agent runtime<br/>agent orchestration"]
  node_runtimecore["Autonomy runtime<br/>background runtime"]
  node_protocols["Protocols<br/>durable workflows"]
  node_tasksruns["Tasks & runs<br/>durable records"]
  node_persistence[("Persistence<br/>repositories")]
end

subgraph group_integrations["Integrations"]
  node_memory["Memory<br/>long-term context"]
  node_knowledge["Knowledge<br/>sources & hygiene"]
  node_connectors["Connectors<br/>event bridge"]
  node_providers["Providers<br/>model adapters"]
  node_tools["Session tools<br/>capability layer"]
  node_skills["Skills<br/>capabilities"]
  node_extensions["Extensions<br/>plugin system<br/>[extensions.ts]"]
end

subgraph group_ops["Ops"]
  node_quality["Quality<br/>eval & gating"]
  node_observability["Observability<br/>tracing & logs"]
  node_deployment["Deploy<br/>runtime wrappers"]
end

node_dashboard -->|"calls"| node_api
node_cli -->|"uses"| node_server
node_electron -->|"boots"| node_server
node_api -->|"routes to"| node_server
node_server -->|"drives"| node_chat
node_server -->|"drives"| node_agents
node_server -->|"coordinates"| node_runtimecore
node_server -->|"orchestrates"| node_protocols
node_server -->|"persists"| node_tasksruns
node_server -->|"stores"| node_memory
node_server -->|"manages"| node_knowledge
node_server -->|"bridges"| node_connectors
node_server -->|"adapts"| node_providers
node_server -->|"assembles"| node_tools
node_server -->|"resolves"| node_skills
node_server -->|"loads"| node_extensions
node_server -->|"uses"| node_persistence
node_server -->|"checks"| node_quality
node_server -->|"traces"| node_observability
node_runtimecore -->|"wakes"| node_agents
node_runtimecore -->|"queues"| node_tasksruns
node_chat -->|"calls models"| node_providers
node_chat -->|"invokes"| node_tools
node_chat -->|"writes"| node_memory
node_connectors -->|"delivers"| node_chat
node_protocols -->|"delegates"| node_agents
node_tasksruns -->|"resumes"| node_runtimecore
node_quality -->|"exposed by"| node_api
node_deployment -->|"packages"| node_electron
node_deployment -->|"hosts"| node_server

click node_dashboard "https://github.com/swarmclawai/swarmclaw/tree/main/src/app"
click node_api "https://github.com/swarmclawai/swarmclaw/tree/main/src/app/api"
click node_server "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server"
click node_chat "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/chat-execution"
click node_agents "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/agents"
click node_runtimecore "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/runtime"
click node_protocols "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/protocols"
click node_tasksruns "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/tasks"
click node_memory "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/memory"
click node_knowledge "https://github.com/swarmclawai/swarmclaw/blob/main/src/lib/server/knowledge-sources.ts"
click node_connectors "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/connectors"
click node_providers "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/providers"
click node_tools "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/session-tools"
click node_skills "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/skills"
click node_extensions "https://github.com/swarmclawai/swarmclaw/blob/main/src/lib/server/extensions.ts"
click node_persistence "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/persistence"
click node_quality "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/quality"
click node_observability "https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/observability"
click node_cli "https://github.com/swarmclawai/swarmclaw/tree/main/src/cli"
click node_electron "https://github.com/swarmclawai/swarmclaw/tree/main/electron"
click node_deployment "https://github.com/swarmclawai/swarmclaw/tree/main/Dockerfile"

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_dashboard,node_cli,node_electron toneBlue
class node_api,node_server toneAmber
class node_chat,node_agents,node_runtimecore,node_protocols,node_tasksruns,node_persistence toneMint
class node_memory,node_knowledge,node_connectors,node_providers,node_tools,node_skills,node_extensions toneRose
class node_quality,node_observability,node_deployment toneIndigo
```

## Components

### Entry points

User-facing and operational shells that drive the shared backend runtime.

- [Dashboard](https://github.com/swarmclawai/swarmclaw/tree/main/src/app): Next.js app · Primary UI surface and domain pages under the App Router. · `src/app`
- [CLI](https://github.com/swarmclawai/swarmclaw/tree/main/src/cli): node command · Operational commands and binary wrapper for setup, diagnostics, updates, and runtime control. · `src/cli`
- [Desktop shell](https://github.com/swarmclawai/swarmclaw/tree/main/electron): Electron app · Desktop wrapper, lifecycle management, paths, and updater integration. · `electron`

### Control plane

Next.js routes and shared server services that implement the product.

- [API routes](https://github.com/swarmclawai/swarmclaw/tree/main/src/app/api): HTTP control plane · Main inbound API surface translating requests into domain services. · `src/app/api`
- [Server libs](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server): domain services · Shared server-side services, repositories, and helpers used by UI, CLI, and desktop. · `src/lib/server`

### Runtime

Execution, autonomy, orchestration, and persistence layers.

- [Chat engine](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/chat-execution): execution pipeline · Prompt building, tool routing, streaming, continuation, and turn finalization. · `src/lib/server/chat-execution`
- [Agent runtime](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/agents): agent orchestration · Agent lifecycle, delegation, swarms, guardrails, and thread/session state. · `src/lib/server/agents`
- [Autonomy runtime](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/runtime): background runtime · Heartbeats, wake loops, queueing, recovery, daemon control, and session-run management. · `src/lib/server/runtime`
- [Protocols](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/protocols): durable workflows · DAG-style flows, branches, loops, subflows, swarms, and protocol runs. · `src/lib/server/protocols`
- [Tasks & runs](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/tasks): durable records · Durable task execution, run ledger, handoff packets, and workflow state. · `src/lib/server/tasks`
- [Persistence](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/persistence): repositories · Local durable storage, repositories, storage context, and workspace-backed state. · `src/lib/server/persistence`

### Integrations

Providers, connectors, memory, and external capability surfaces.

- [Memory](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/memory): long-term context · Tiered memory, retrieval, dreams, reflection, consolidation, and session scope. · `src/lib/server/memory`
- [Knowledge](https://github.com/swarmclawai/swarmclaw/blob/main/src/lib/server/knowledge-sources.ts): sources & hygiene · Knowledge sources, import, hygiene, and retrieval-facing content. · `src/lib/server/knowledge-sources.ts`
- [Connectors](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/connectors): event bridge · Slack, Discord, email, file queues, SwarmDock, SwarmFeed, and other external channels. · `src/lib/server/connectors`
- [Providers](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/providers): model adapters · OpenAI-compatible, CLI-backed, Ollama, OpenClaw, and provider diagnostics. · `src/lib/providers`
- [Session tools](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/session-tools): capability layer · Per-session tool assembly for files, web, memory, skills, delegates, and platform actions. · `src/lib/server/session-tools`
- [Skills](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/skills): capabilities · Skill discovery, runtime resolution, learned skills, and skill suggestions. · `src/lib/server/skills`
- [Extensions](https://github.com/swarmclawai/swarmclaw/blob/main/src/lib/server/extensions.ts): plugin system · Builtin and managed extensions plus approval and resource handling. · `src/lib/server/extensions.ts`

### Ops

Quality, observability, deployment, and wrapper tooling.

- [Quality](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/quality): eval & gating · Architecture health, release readiness, eval suites, and operator safety checks. · `src/lib/quality`
- [Observability](https://github.com/swarmclawai/swarmclaw/tree/main/src/lib/server/observability): tracing & logs · OpenTelemetry, local observability, activity, and runtime diagnostics. · `src/lib/server/observability`
- [Deploy](https://github.com/swarmclawai/swarmclaw/tree/main/Dockerfile): runtime wrappers · Container and platform deployment manifests for hosted and self-hosted operation. · `Dockerfile`

## Connections

- Dashboard → API routes: calls · UI actions resolve through route handlers and shared client helpers.
- CLI → Server libs: uses · CLI commands invoke the same server-side services as the UI.
- Desktop shell → Server libs: boots · Desktop shell starts and supervises the shared backend runtime.
- API routes → Server libs: routes to · HTTP endpoints dispatch into shared domain services.
- Server libs → Chat engine: drives · Chat requests flow into the execution pipeline.
- Server libs → Agent runtime: drives · Agent state, delegation, and lifecycle are handled here.
- Server libs → Autonomy runtime: coordinates · Background work and recovery are managed by the runtime layer.
- Server libs → Protocols: orchestrates · Structured workflows execute through protocol services.
- Server libs → Tasks & runs: persists · Durable task and run records are written and queried here.
- Server libs → Memory: stores · Long-term context is consolidated and retrieved from memory subsystems.
- Server libs → Knowledge: manages · Knowledge sources and hygiene are exposed as a server boundary.
- Server libs → Connectors: bridges · External channel delivery and inbound webhooks pass through connector services.
- Server libs → Providers: adapts · Model access and diagnostics are abstracted behind provider adapters.
- Server libs → Session tools: assembles · Session-specific tool sets are built before each turn.
- Server libs → Skills: resolves · Skill discovery and runtime eligibility feed agent capability selection.
- Server libs → Extensions: loads · Extensions contribute capabilities and managed resources.
- Server libs → Persistence: uses · Repositories and workspace-backed state provide durable storage.
- Server libs → Quality: checks · Quality services gate architecture and release readiness.
- Server libs → Observability: traces · Runtime activity, logs, and telemetry are emitted for inspection.
- Autonomy runtime → Agent runtime: wakes · Heartbeat and daemon loops resume or retry agent work.
- Autonomy runtime → Tasks & runs: queues · Background execution is coordinated through task and run queues.
- Chat engine → Providers: calls models · Prompted turns stream through model providers.
- Chat engine → Session tools: invokes · Tool calls are routed through the session tool layer.
- Chat engine → Memory: writes · Turns can mutate or retrieve durable context.
- Connectors → Chat engine: delivers · Inbound and outbound messages can attach to chat sessions.
- Protocols → Agent runtime: delegates · Protocol steps can spawn or coordinate agent work.
- Tasks & runs → Autonomy runtime: resumes · Durable work records are rehydrated by runtime recovery.
- Quality → API routes: exposed by · Operator-facing eval and readiness checks are surfaced via API routes.
- Deploy → Desktop shell: packages · Deployment artifacts include the desktop build path.
- Deploy → Server libs: hosts · Container and platform manifests run the shared backend.