# openswarm-ai/openswarm architecture

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

- Interactive diagram: https://gitdiagram.com/openswarm-ai/openswarm
- Repository: https://github.com/openswarm-ai/openswarm

## Overview

1. **Overall shape**
   - Open Swarm is a local desktop orchestrator, not a traditional web app.
   - The runtime is split into three main boundaries: **Electron shell** for packaging and native integration, **React/TypeScript frontend** for all user interaction, and a **FastAPI/Python backend** for orchestration, persistence, and agent execution.

2. **Electron as the desktop host**
   - `electron/main.js` is the top-level desktop entry point.
   - It owns app startup, auto-updates, packaging, and the bundled Python environment.
   - The frontend and backend are launched together under Electron during development and in packaged builds, so the desktop app is the actual deployment unit.

3. **Frontend responsibilities**
   - The `frontend/` app is the primary UI layer: dashboard canvas, agent chat, skills/tools/modes/settings, and output editors.
   - It is state-heavy and uses Redux slices under `frontend/src/shared/state` to model agents, dashboards, models, tools, modes, skills, sessions, streaming state, and updates.
   - A dedicated WebSocket manager and shared hooks connect UI state to live backend events.

4. **Backend responsibilities**
   - `backend/main.py` starts a FastAPI service on the local machine.
   - The backend exposes REST endpoints for CRUD/configuration and WebSocket endpoints for streaming agent activity and approvals.
   - It also owns persistent local storage, session lifecycle, tool discovery, registry proxies, and file-system coordination.

5. **Agent orchestration is the core subsystem**
   - `backend/apps/agents/` is the orchestration layer for launching, managing, and monitoring agents.
   - It handles agent lifecycle, streaming output, approval gating, retries, metrics, history, and specialized browser/invoke workflows.
   - The design is centered on parallel sessions: each agent can run independently while the UI aggregates their status into one workspace.

6. **Conversation and tool-call streaming**
   - The live chat experience is driven by backend-to-frontend streaming over WebSockets.
   - Streaming includes token deltas, tool calls, approvals, cost updates, and session events.
   - The frontend renders this as chat bubbles, tool bubbles, approval bars, and branch navigation, while the backend remains the source of truth for execution state.

7. **Git worktree isolation is a key architectural boundary**
   - The backend’s session and workspace code manages isolated git worktrees per agent.
   - This lets multiple agents work in parallel without overwriting each other’s branch state.
   - The UI exposes that isolation through the dashboard, diff viewer, and session navigation, but the actual filesystem/branch mechanics live in the backend.

8. **Dashboard and spatial workspace**
   - `backend/apps/dashboards`, `dashboard_layout`, and the frontend dashboard pages together implement the “spatial canvas” model.
   - Dashboard state is persisted separately from agent sessions so users can arrange cards, open browser/view/agent cards, and resume layouts.
   - The dashboard is the main coordination surface, while chat is the detailed interaction surface.

9. **Tools, MCP, and external integrations**
   - `backend/apps/tools_lib`, `mcp_registry`, `discord_mcp_shim`, and `google_workspace_mcp_shim` cover tool discovery and integration.
   - The system supports MCP servers over stdio, HTTP, and SSE, with OAuth support where needed.
   - Tool policy, discovery, and registry browsing are first-class, because agent capabilities depend on which tools are connected and allowed.

10. **Modes, skills, and prompt composition**
   - `backend/apps/modes`, `skills`, and the prompt manager under `backend/apps/agents/manager/prompt` define how agents are instructed.
   - Modes constrain system prompts and tool access; skills are synced and surfaced for reuse; prompt templates/attachments shape individual runs.
   - This is a control-plane layer for agent behavior, separate from the execution/runtime layer.

11. **Views and outputs form a second runtime surface**
   - `backend/apps/outputs` generates and runs interactive artifacts, including HTML/JS/CSS views and backend-backed runtime processes.
   - The frontend has dedicated editors, previews, run dialogs, and code panels for this subsystem.
   - This is distinct from agent chat: it is for produced artifacts and live preview, not just conversation.

12. **Local persistence and configuration**
   - Most app state is local and file-based rather than database-backed.
   - `backend/config` and `backend/apps/settings` manage install IDs, JSON stores, credentials, redaction, and app settings.
   - The frontend settings pages map directly onto these backend stores, so config changes are persisted locally and reloaded across restarts.

13. **Optional cloud/external dependencies**
   - The product is “100% local” in the sense that the orchestration stack runs on the user machine, but it still depends on external services when enabled.
   - Key outside integrations include Anthropic/Claude APIs for model access, GitHub Releases for updates, Google OAuth for Workspace tools, and package/proxy registries for MCP and skills discovery.

14. **Support systems and release pipeline**
   - `openswarm-edge/` is a separate edge/sandbox service used for hosted or published output scenarios, not the main desktop runtime.
   - `linter/`, `scripts/`, `e2e/`, and the large backend test suite show that architecture is guarded by repo-level checks, smoke tests, and release verification.
   - This repo is built like a desktop platform: core runtime, integration shims, artifact publishing, and strong CI/release gating.

Main entry points: [`frontend/src/app/Main.tsx`](https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/Main.tsx) (App shell), [`backend/main.py`](https://github.com/openswarm-ai/openswarm/blob/main/backend/main.py) (FastAPI main), [`frontend/src/shared/state/store.ts`](https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/shared/state/store.ts) (Redux state), [`backend/apps/agents/agent_manager.py`](https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/agents/agent_manager.py) (Agent runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop host"]
  node_electron_main["Electron main<br/>desktop host<br/>[main.js]"]
  node_electron_preload["Preload<br/>desktop bridge<br/>[preload.js]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_shell["App shell<br/>ui shell<br/>[Main.tsx]"]
  node_dashboard_ui["Dashboard<br/>spatial workspace<br/>[Dashboard.tsx]"]
  node_agent_chat_ui["Agent chat<br/>conversation UI<br/>[AgentChat.tsx]"]
  node_views_ui["Views<br/>artifact runtime UI<br/>[Views.tsx]"]
  node_tools_ui["Tools<br/>integration UI<br/>[Tools.tsx]"]
  node_settings_ui["Settings<br/>config UI<br/>[Settings.tsx]"]
  node_frontend_state[("Redux state<br/>client state<br/>[store.ts]")]
  node_ws_manager["WebSocket mgr<br/>event sync"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI main<br/>api host<br/>[main.py]"]
  node_agent_orchestrator["Agent runtime<br/>orchestration<br/>[agent_manager.py]"]
  node_session_workspace[("Session store<br/>session/worktree<br/>[session_store.py]")]
  node_dashboard_store[("Dashboard store<br/>workspace state<br/>[dashboards.py]")]
  node_outputs_runtime["Outputs runtime<br/>artifact execution<br/>[runtime.py]"]
  node_tools_lib["Tool library<br/>tool discovery<br/>[tools_lib.py]"]
  node_settings_store[("Settings store<br/>local config<br/>[settings.py]")]
  node_swarm_core["Swarm core<br/>domain model<br/>[swarm.py]"]
end

subgraph group_integrations["Integrations"]
  node_mcp_registry["MCP registry<br/>registry proxy<br/>[mcp_registry.py]"]
end

subgraph group_support["Support"]
  node_edge_service["Edge service<br/>published runtime<br/>[main.py]"]
  node_ci_release["CI and release<br/>gating pipeline"]
end

node_electron_main -->|"launches"| node_frontend_shell
node_electron_main -->|"starts"| node_backend_main
node_electron_main -->|"bridges"| node_electron_preload
node_frontend_shell -->|"navigates"| node_dashboard_ui
node_frontend_shell -->|"navigates"| node_agent_chat_ui
node_frontend_shell -->|"navigates"| node_views_ui
node_frontend_shell -->|"navigates"| node_tools_ui
node_frontend_shell -->|"navigates"| node_settings_ui
node_frontend_shell -->|"uses"| node_frontend_state
node_dashboard_ui -->|"reads/writes"| node_frontend_state
node_agent_chat_ui -->|"reads/writes"| node_frontend_state
node_views_ui -->|"reads/writes"| node_frontend_state
node_tools_ui -->|"reads/writes"| node_frontend_state
node_settings_ui -->|"reads/writes"| node_frontend_state
node_frontend_state -->|"syncs via"| node_ws_manager
node_ws_manager -->|"streams"| node_backend_main
node_backend_main -->|"hosts"| node_agent_orchestrator
node_agent_orchestrator -->|"uses"| node_session_workspace
node_agent_orchestrator -->|"drives"| node_outputs_runtime
node_backend_main -->|"persists"| node_dashboard_store
node_backend_main -->|"persists"| node_settings_store
node_backend_main -->|"serves"| node_tools_lib
node_tools_lib -->|"discovers"| node_mcp_registry
node_tools_lib -->|"reads"| node_settings_store
node_agent_orchestrator -->|"depends on"| node_swarm_core
node_dashboard_store -.->|"links"| node_session_workspace
node_outputs_runtime -->|"publishes to"| node_edge_service
node_ci_release -.->|"verifies"| node_electron_main
node_ci_release -.->|"verifies"| node_backend_main
node_ci_release -.->|"verifies"| node_frontend_shell

click node_electron_main "https://github.com/openswarm-ai/openswarm/blob/main/electron/main.js"
click node_electron_preload "https://github.com/openswarm-ai/openswarm/blob/main/electron/preload.js"
click node_frontend_shell "https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/Main.tsx"
click node_dashboard_ui "https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/pages/Dashboard/Dashboard.tsx"
click node_agent_chat_ui "https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/pages/AgentChat/AgentChat.tsx"
click node_views_ui "https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/pages/Views/Views.tsx"
click node_tools_ui "https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/pages/Tools/Tools.tsx"
click node_settings_ui "https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/pages/Settings/Settings.tsx"
click node_frontend_state "https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/shared/state/store.ts"
click node_ws_manager "https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/shared/ws/WebSocketManager.ts"
click node_backend_main "https://github.com/openswarm-ai/openswarm/blob/main/backend/main.py"
click node_agent_orchestrator "https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/agents/agent_manager.py"
click node_session_workspace "https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/agents/manager/session/session_store.py"
click node_dashboard_store "https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/dashboards/dashboards.py"
click node_outputs_runtime "https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/outputs/runtime.py"
click node_tools_lib "https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/tools_lib/tools_lib.py"
click node_mcp_registry "https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/mcp_registry/mcp_registry.py"
click node_settings_store "https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/settings/settings.py"
click node_swarm_core "https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/swarm/swarm.py"
click node_edge_service "https://github.com/openswarm-ai/openswarm/blob/main/openswarm-edge/app/main.py"
click node_ci_release "https://github.com/openswarm-ai/openswarm/blob/main/.github/workflows/release-windows.yml"

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_electron_main,node_electron_preload toneBlue
class node_frontend_shell,node_dashboard_ui,node_agent_chat_ui,node_views_ui,node_tools_ui,node_settings_ui,node_frontend_state,node_ws_manager toneAmber
class node_backend_main,node_agent_orchestrator,node_session_workspace,node_dashboard_store,node_outputs_runtime,node_tools_lib,node_settings_store,node_swarm_core toneMint
class node_mcp_registry toneRose
class node_edge_service,node_ci_release toneIndigo
```

## Components

### Desktop host

Electron packaging, native integration, and app launch

- [Electron main](https://github.com/openswarm-ai/openswarm/blob/main/electron/main.js): desktop host · Top-level desktop entry point for startup, updates, and bundled runtime launch · `electron/main.js`
- [Preload](https://github.com/openswarm-ai/openswarm/blob/main/electron/preload.js): desktop bridge · IPC and webview bridge into the desktop shell · `electron/preload.js`

### Frontend

React/TypeScript UI and client state

- [App shell](https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/Main.tsx): ui shell · Root UI composition and cross-page layout · `frontend/src/app/Main.tsx`
- [Dashboard](https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/pages/Dashboard/Dashboard.tsx): spatial workspace · Canvas-based workspace for cards, agent panes, and layout interactions · `frontend/src/app/pages/Dashboard/Dashboard.tsx`
- [Agent chat](https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/pages/AgentChat/AgentChat.tsx): conversation UI · Streaming chat surface with approvals, tool bubbles, and branch navigation · `frontend/src/app/pages/AgentChat/AgentChat.tsx`
- [Views](https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/pages/Views/Views.tsx): artifact runtime UI · Editors and previews for generated interactive artifacts · `frontend/src/app/pages/Views/Views.tsx`
- [Tools](https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/pages/Tools/Tools.tsx): integration UI · Tool connections, registry browsing, and MCP configuration screens · `frontend/src/app/pages/Tools/Tools.tsx`
- [Settings](https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/app/pages/Settings/Settings.tsx): config UI · Local app, model, privacy, and subscription settings screens · `frontend/src/app/pages/Settings/Settings.tsx`
- [Redux state](https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/shared/state/store.ts): client state · Shared slices for agents, dashboards, models, tools, modes, sessions, streaming, and updates · `frontend/src/shared/state/store.ts`
- [WebSocket mgr](https://github.com/openswarm-ai/openswarm/blob/main/frontend/src/shared/ws/WebSocketManager.ts): event sync · Client-side live event and streaming connection manager · `frontend/src/shared/ws/WebSocketManager.ts`

### Backend

FastAPI orchestration, persistence, and local APIs

- [FastAPI main](https://github.com/openswarm-ai/openswarm/blob/main/backend/main.py): api host · Local backend service entry point · `backend/main.py`
- [Agent runtime](https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/agents/agent_manager.py): orchestration · Launches, monitors, and streams parallel agent sessions · `backend/apps/agents/agent_manager.py`
- [Session store](https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/agents/manager/session/session_store.py): session/worktree · Session lifecycle, history, and isolated git worktrees · `backend/apps/agents/manager/session/session_store.py`
- [Dashboard store](https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/dashboards/dashboards.py): workspace state · Persistent dashboard layouts and spatial workspace state · `backend/apps/dashboards/dashboards.py`
- [Outputs runtime](https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/outputs/runtime.py): artifact execution · Builds, runs, and publishes interactive output artifacts · `backend/apps/outputs/runtime.py`
- [Tool library](https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/tools_lib/tools_lib.py): tool discovery · Tool taxonomy, MCP config, OAuth tokens, and discovery · `backend/apps/tools_lib/tools_lib.py`
- [Settings store](https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/settings/settings.py): local config · Persistent JSON-backed settings, credentials, redaction, and install identity · `backend/apps/settings/settings.py`
- [Swarm core](https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/swarm/swarm.py): domain model · Shared entity and registry layer for apps, sessions, skills, and workflows · `backend/apps/swarm/swarm.py`

### Integrations

Tool discovery, MCP, OAuth, and external service bridges

- [MCP registry](https://github.com/openswarm-ai/openswarm/blob/main/backend/apps/mcp_registry/mcp_registry.py): registry proxy · Registry browsing and server discovery for external tools · `backend/apps/mcp_registry/mcp_registry.py`

### Support

Release pipeline, tests, and edge/runtime support

- [Edge service](https://github.com/openswarm-ai/openswarm/blob/main/openswarm-edge/app/main.py): published runtime · Separate sandbox/edge service for hosted or published outputs · `openswarm-edge/app/main.py`
- [CI and release](https://github.com/openswarm-ai/openswarm/blob/main/.github/workflows/release-windows.yml): gating pipeline · Linting, E2E, packaging, verification, and release workflows · `.github/workflows/release-windows.yml`

## Connections

- Electron main → App shell: launches · Electron starts the desktop UI
- Electron main → FastAPI main: starts · Electron hosts the local backend during development and packaged runs
- Electron main → Preload: bridges · Desktop IPC/webview bridge for the renderer
- App shell → Dashboard: navigates · Main shell exposes the spatial workspace
- App shell → Agent chat: navigates · Main shell exposes agent conversation
- App shell → Views: navigates · Main shell exposes artifact editing and previews
- App shell → Tools: navigates · Main shell exposes integrations management
- App shell → Settings: navigates · Main shell exposes local configuration
- App shell → Redux state: uses · UI pages share centralized client state
- Dashboard → Redux state: reads/writes · Dashboard cards and layout interact with shared state
- Agent chat → Redux state: reads/writes · Chat, streaming, and approvals are state-driven
- Views → Redux state: reads/writes · Artifact editor and preview state is shared
- Tools → Redux state: reads/writes · Tool connections and registry views are state-driven
- Settings → Redux state: reads/writes · Settings forms bind to persisted client state
- Redux state → WebSocket mgr: syncs via · Shared state is updated from live backend events
- WebSocket mgr → FastAPI main: streams · WebSocket channel for tokens, tool calls, approvals, and session events
- FastAPI main → Agent runtime: hosts · Backend exposes orchestration and execution services
- Agent runtime → Session store: uses · Agent runs are isolated by session and git worktree
- Agent runtime → Outputs runtime: drives · Agents can create and run interactive outputs
- FastAPI main → Dashboard store: persists · Dashboard layouts are stored separately from sessions
- FastAPI main → Settings store: persists · Local app and credential configuration lives in file-backed stores
- FastAPI main → Tool library: serves · Backend exposes tool discovery and policy APIs
- Tool library → MCP registry: discovers · Registry-backed MCP server discovery and browsing
- Tool library → Settings store: reads · Tool connections depend on local credentials and config
- Agent runtime → Swarm core: depends on · Execution uses shared swarm/domain entities and registry logic
- Dashboard store → Session store: links · Workspace layout references agent/session state
- Outputs runtime → Edge service: publishes to · Some outputs target the separate edge sandbox runtime
- CI and release → Electron main: verifies · Release pipeline validates desktop packaging and host behavior
- CI and release → FastAPI main: verifies · CI covers backend correctness and API behavior
- CI and release → App shell: verifies · CI covers frontend builds and E2E flows