# langchain-ai/open-swe architecture

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

- Interactive diagram: https://gitdiagram.com/langchain-ai/open-swe
- Repository: https://github.com/langchain-ai/open-swe

## Overview

#### Purpose and Runtime Entry Points
Open SWE is a deployable software-engineering agent system: it receives work from dashboard, GitHub, Slack, Linear, or schedules; executes durable agent runs; works in isolated environments; and delivers or reviews pull requests. The custom FastAPI application is `agent/webapp.py`, with server startup in `agent/server.py`; LangGraph graph entrypoints are registered through `agent/graphs/agent.py`, `agent/graphs/reviewer.py`, and `agent/graphs/scheduler.py`. `langgraph.json` and `langgraph.desktop.json` define runtime deployment variants.

#### Invocation and Thread Lifecycle
Inbound integrations normalize requests into durable threads and invocations. Thread state, access, run views, plans, summaries, and approvals are concentrated in `agent/threads/routes.py`, `agent/threads/runs.py`, and `agent/threads/workflow_approval.py`. Dispatch selects an execution path based on source and task type in `agent/dispatch.py` and `agent/invocation.py`. A thread persists conversation/work context across multiple LangGraph runs; cloud coding threads bind to a persistent sandbox, while read-only review/chat can avoid one.

#### Agent Graph Assembly and Guardrails
The principal coding graph plans, investigates, edits, validates, and delivers changes; reviewer, analyzer, and chat graphs specialize for read-only PR work and repository-style learning. Graph composition resides in `agent/graphs/agent.py`, `agent/graphs/reviewer.py`, and `agent/graphs/analyzer.py`. Cross-cutting middleware governs preparation, model selection/fallback, dynamic tool exposure, retries, validation, tracing, plan mode, and push restrictions: `agent/middleware/prepare_run.py`, `agent/middleware/model_selection.py`, `agent/middleware/dynamic_tools.py`, and `agent/middleware/workflow_push_guard.py`. Prompts and tool contracts are versioned as repository resources under `agent/resources/prompts/system/main.md`, `agent/resources/prompts/reviewer/main.md`, and `agent/resources/prompts/tools/`.

#### Sandboxed Execution Boundary
Coding execution is isolated behind a provider-neutral sandbox lifecycle. `agent/sandboxes/lifecycle.py` creates, recovers, and manages persistent environments; `agent/sandboxes/repo_prep.py` prepares repositories and workspace setup; `agent/sandboxes/providers/registry.py` selects providers. Supported implementations include LangSmith, Modal, Daytona, Runloop, E2B, and local execution under `agent/sandboxes/providers/`. This boundary protects server-held credentials and avoids silently replacing unreachable sandboxes that may contain uncommitted work.

#### Integrations, Delivery, and Automation
GitHub is both an ingress and delivery boundary: webhook handling, authenticated API access, PR context/diffs, comments, checks, and PR operations reside in `agent/github/webhook.py`, `agent/github/pull_requests.py`, and `agent/github/checks.py`. Slack and Linear provide parallel event-driven entry points in `agent/slack/routes.py`, `agent/slack/events.py`, and `agent/linear/webhook.py`. Scheduled automations and CI monitoring flow through `agent/schedules/store.py`, `agent/scheduler.py`, and `agent/baby_sit.py`. The expedited-review subsystem adds opt-in approval/readiness/voting workflows under `agent/expedited_review/`.

#### State, Identity, and Observability
PostgreSQL-backed ORM and migrations define durable product state, including analytics, threads/PRs, users, and workspaces: `agent/database/orm.py`, `agent/database/postgres.py`, and `agent/database/migrations/versions/`. Authorization and credential scoping are enforced in `agent/users/authorization.py`, `agent/credential_scope.py`, and `agent/encryption.py`. Analytics uses capture/outbox/worker-style stages in `agent/analytics/capture.py`, `agent/analytics/outbox.py`, and `agent/analytics/worker.py`. LangSmith is the default tracing and sandbox service; MCP integrations are modeled and routed in `agent/mcp/runtime.py` and `agent/mcp/routes.py`.

#### Product Surfaces
The browser dashboard is a TypeScript/React Vite application rooted at `ui/src/router.tsx`, with agent-thread streaming UI in `ui/src/features/agents/lib/stream/AgentStreamProvider.tsx` and server proxy boundaries in `ui/server/backend-proxy.ts`. The experimental Electron desktop client launches/supervises a local backend and operates on allowlisted local projects via `desktop/src/main.cts`, `desktop/src/backend-supervisor.cjs`, and `desktop/src/project-store.cts`. Desktop-local agent behavior bridges through `agent/desktop.py` and `agent/desktop_branch.py`.

Main entry points: [`agent/webapp.py`](https://github.com/langchain-ai/open-swe/blob/main/agent/webapp.py) (FastAPI application), [`agent/graphs/agent.py`](https://github.com/langchain-ai/open-swe/blob/main/agent/graphs/agent.py) (Coding agent graph), [`agent/middleware/prepare_run.py`](https://github.com/langchain-ai/open-swe/blob/main/agent/middleware/prepare_run.py) (Execution middleware), [`agent/threads/routes.py`](https://github.com/langchain-ai/open-swe/blob/main/agent/threads/routes.py) (Threads and run lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["Product surfaces"]
  node_dashboard["React dashboard<br/>web client<br/>[router.tsx]"]
  node_desktop["Electron desktop<br/>desktop client<br/>[main.cts]"]
  node_integration_ingress["GitHub, Slack &amp; Linear<br/>event ingress<br/>[webhook.py]"]
  node_automation["Schedules &amp; CI monitor<br/>automation<br/>[scheduler.py]"]
  node_backend_proxy["Dashboard backend proxy<br/>server proxy<br/>[backend-proxy.ts]"]
end

subgraph group_control["API and orchestration"]
  node_webapp["FastAPI application<br/>API server<br/>[webapp.py]"]
  node_desktop_bridge["Desktop agent bridge<br/>local backend adapter<br/>[desktop.py]"]
  node_threads["Threads and run lifecycle<br/>durable workflow state<br/>[routes.py]"]
  node_dispatch{{"Invocation dispatch<br/>router<br/>[dispatch.py]"}}
end

subgraph group_graphs["Agent execution"]
  node_coding_graph["Coding agent graph<br/>LangGraph workflow<br/>[agent.py]"]
  node_review_graph["Review and analysis graphs<br/>LangGraph workflows<br/>[reviewer.py]"]
  node_guardrails["Execution middleware<br/>policy layer<br/>[prepare_run.py]"]
  node_prompts_tools["Versioned prompts and tools<br/>agent resources<br/>[main.md]"]
end

subgraph group_sandbox["Sandbox boundary"]
  node_sandbox_lifecycle["Sandbox lifecycle<br/>environment manager<br/>[lifecycle.py]"]
  node_repo_prep["Repository preparation<br/>workspace setup<br/>[repo_prep.py]"]
  node_sandbox_providers["Sandbox providers<br/>provider registry<br/>[registry.py]"]
end

subgraph group_state["State and external services"]
  node_github_delivery["GitHub PR delivery<br/>GitHub boundary<br/>[pull_requests.py]"]
  node_postgres[("PostgreSQL product state<br/>database<br/>[postgres.py]")]
  node_access["Authorization and credentials<br/>security boundary<br/>[authorization.py]"]
  node_analytics["Analytics pipeline<br/>outbox worker<br/>[outbox.py]"]
  node_mcp["MCP runtime<br/>integration runtime<br/>[runtime.py]"]
  node_langsmith["LangSmith<br/>tracing service"]
end

node_dashboard -->|"browser requests"| node_backend_proxy
node_backend_proxy -->|"proxies"| node_webapp
node_desktop -->|"local agent requests"| node_desktop_bridge
node_desktop_bridge -->|"local backend"| node_webapp
node_integration_ingress -->|"webhooks"| node_webapp
node_automation -->|"automation triggers"| node_webapp
node_webapp -->|"creates and reads"| node_threads
node_threads -->|"persists context and runs"| node_postgres
node_webapp -->|"invokes"| node_dispatch
node_dispatch -->|"coding tasks"| node_coding_graph
node_dispatch -->|"review and chat tasks"| node_review_graph
node_coding_graph -->|"governed by"| node_guardrails
node_review_graph -->|"governed by"| node_guardrails
node_guardrails -->|"loads contracts"| node_prompts_tools
node_coding_graph -->|"persistent coding environment"| node_sandbox_lifecycle
node_sandbox_lifecycle -->|"prepares workspace"| node_repo_prep
node_sandbox_lifecycle -->|"selects provider"| node_sandbox_providers
node_coding_graph -->|"delivers changes"| node_github_delivery
node_review_graph -->|"reads PRs and posts review"| node_github_delivery
node_webapp -->|"authorizes requests"| node_access
node_guardrails -->|"traces runs"| node_langsmith
node_coding_graph -.->|"uses external tools"| node_mcp
node_threads -.->|"emits product events"| node_analytics

click node_dashboard "https://github.com/langchain-ai/open-swe/blob/main/ui/src/router.tsx"
click node_desktop "https://github.com/langchain-ai/open-swe/blob/main/desktop/src/main.cts"
click node_integration_ingress "https://github.com/langchain-ai/open-swe/blob/main/agent/github/webhook.py"
click node_automation "https://github.com/langchain-ai/open-swe/blob/main/agent/scheduler.py"
click node_webapp "https://github.com/langchain-ai/open-swe/blob/main/agent/webapp.py"
click node_backend_proxy "https://github.com/langchain-ai/open-swe/blob/main/ui/server/backend-proxy.ts"
click node_desktop_bridge "https://github.com/langchain-ai/open-swe/blob/main/agent/desktop.py"
click node_threads "https://github.com/langchain-ai/open-swe/blob/main/agent/threads/routes.py"
click node_dispatch "https://github.com/langchain-ai/open-swe/blob/main/agent/dispatch.py"
click node_coding_graph "https://github.com/langchain-ai/open-swe/blob/main/agent/graphs/agent.py"
click node_review_graph "https://github.com/langchain-ai/open-swe/blob/main/agent/graphs/reviewer.py"
click node_guardrails "https://github.com/langchain-ai/open-swe/blob/main/agent/middleware/prepare_run.py"
click node_prompts_tools "https://github.com/langchain-ai/open-swe/blob/main/agent/resources/prompts/system/main.md"
click node_sandbox_lifecycle "https://github.com/langchain-ai/open-swe/blob/main/agent/sandboxes/lifecycle.py"
click node_repo_prep "https://github.com/langchain-ai/open-swe/blob/main/agent/sandboxes/repo_prep.py"
click node_sandbox_providers "https://github.com/langchain-ai/open-swe/blob/main/agent/sandboxes/providers/registry.py"
click node_github_delivery "https://github.com/langchain-ai/open-swe/blob/main/agent/github/pull_requests.py"
click node_postgres "https://github.com/langchain-ai/open-swe/blob/main/agent/database/postgres.py"
click node_access "https://github.com/langchain-ai/open-swe/blob/main/agent/users/authorization.py"
click node_analytics "https://github.com/langchain-ai/open-swe/blob/main/agent/analytics/outbox.py"
click node_mcp "https://github.com/langchain-ai/open-swe/blob/main/agent/mcp/runtime.py"

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_desktop,node_integration_ingress,node_automation,node_backend_proxy toneBlue
class node_webapp,node_desktop_bridge,node_threads,node_dispatch toneAmber
class node_coding_graph,node_review_graph,node_guardrails,node_prompts_tools toneMint
class node_sandbox_lifecycle,node_repo_prep,node_sandbox_providers toneRose
class node_github_delivery,node_postgres,node_access,node_analytics,node_mcp,node_langsmith toneIndigo
```

## Components

### Product surfaces

- [React dashboard](https://github.com/langchain-ai/open-swe/blob/main/ui/src/router.tsx): web client · Thread streaming interface. · `ui/src/router.tsx`
- [Electron desktop](https://github.com/langchain-ai/open-swe/blob/main/desktop/src/main.cts): desktop client · Supervises a local backend for allowlisted projects. · `desktop/src/main.cts`
- [GitHub, Slack & Linear](https://github.com/langchain-ai/open-swe/blob/main/agent/github/webhook.py): event ingress · Webhook and event-driven work sources. · `agent/github/webhook.py`
- [Schedules & CI monitor](https://github.com/langchain-ai/open-swe/blob/main/agent/scheduler.py): automation · Triggers scheduled work and CI follow-up. · `agent/scheduler.py`
- [Dashboard backend proxy](https://github.com/langchain-ai/open-swe/blob/main/ui/server/backend-proxy.ts): server proxy · `ui/server/backend-proxy.ts`

### API and orchestration

- [FastAPI application](https://github.com/langchain-ai/open-swe/blob/main/agent/webapp.py): API server · Custom server entry surface for product and integration requests. · `agent/webapp.py`
- [Desktop agent bridge](https://github.com/langchain-ai/open-swe/blob/main/agent/desktop.py): local backend adapter · `agent/desktop.py`
- [Threads and run lifecycle](https://github.com/langchain-ai/open-swe/blob/main/agent/threads/routes.py): durable workflow state · Owns thread context, runs, plans, summaries, and approvals. · `agent/threads/routes.py`
- [Invocation dispatch](https://github.com/langchain-ai/open-swe/blob/main/agent/dispatch.py): router · Selects execution by source and task type. · `agent/dispatch.py`

### Agent execution

- [Coding agent graph](https://github.com/langchain-ai/open-swe/blob/main/agent/graphs/agent.py): LangGraph workflow · Plans, investigates, edits, validates, and delivers changes. · `agent/graphs/agent.py`
- [Review and analysis graphs](https://github.com/langchain-ai/open-swe/blob/main/agent/graphs/reviewer.py): LangGraph workflows · Read-only PR review, repository analysis, and chat paths. · `agent/graphs/reviewer.py`
- [Execution middleware](https://github.com/langchain-ai/open-swe/blob/main/agent/middleware/prepare_run.py): policy layer · Applies model, tool, retry, validation, tracing, and push controls. · `agent/middleware/prepare_run.py`
- [Versioned prompts and tools](https://github.com/langchain-ai/open-swe/blob/main/agent/resources/prompts/system/main.md): agent resources · `agent/resources/prompts/system/main.md`

### Sandbox boundary

- [Sandbox lifecycle](https://github.com/langchain-ai/open-swe/blob/main/agent/sandboxes/lifecycle.py): environment manager · Creates and recovers persistent coding environments. · `agent/sandboxes/lifecycle.py`
- [Repository preparation](https://github.com/langchain-ai/open-swe/blob/main/agent/sandboxes/repo_prep.py): workspace setup · `agent/sandboxes/repo_prep.py`
- [Sandbox providers](https://github.com/langchain-ai/open-swe/blob/main/agent/sandboxes/providers/registry.py): provider registry · Selects LangSmith, Modal, Daytona, Runloop, E2B, or local execution. · `agent/sandboxes/providers/registry.py`

### State and external services

- [GitHub PR delivery](https://github.com/langchain-ai/open-swe/blob/main/agent/github/pull_requests.py): GitHub boundary · Supplies PR context and publishes comments, checks, and PR operations. · `agent/github/pull_requests.py`
- [PostgreSQL product state](https://github.com/langchain-ai/open-swe/blob/main/agent/database/postgres.py): database · Durable threads, PRs, users, workspaces, and analytics state. · `agent/database/postgres.py`
- [Authorization and credentials](https://github.com/langchain-ai/open-swe/blob/main/agent/users/authorization.py): security boundary · Scopes access and encrypts credentials. · `agent/users/authorization.py`
- [Analytics pipeline](https://github.com/langchain-ai/open-swe/blob/main/agent/analytics/outbox.py): outbox worker · Capture, durable outbox, and worker delivery stages. · `agent/analytics/outbox.py`
- [MCP runtime](https://github.com/langchain-ai/open-swe/blob/main/agent/mcp/runtime.py): integration runtime · `agent/mcp/runtime.py`
- **LangSmith**: tracing service · Default tracing service and a sandbox provider.

## Connections

- React dashboard → Dashboard backend proxy: browser requests
- Dashboard backend proxy → FastAPI application: proxies
- Electron desktop → Desktop agent bridge: local agent requests
- Desktop agent bridge → FastAPI application: local backend
- GitHub, Slack & Linear → FastAPI application: webhooks
- Schedules & CI monitor → FastAPI application: automation triggers
- FastAPI application → Threads and run lifecycle: creates and reads
- Threads and run lifecycle → PostgreSQL product state: persists context and runs
- FastAPI application → Invocation dispatch: invokes
- Invocation dispatch → Coding agent graph: coding tasks
- Invocation dispatch → Review and analysis graphs: review and chat tasks
- Coding agent graph → Execution middleware: governed by
- Review and analysis graphs → Execution middleware: governed by
- Execution middleware → Versioned prompts and tools: loads contracts
- Coding agent graph → Sandbox lifecycle: persistent coding environment
- Sandbox lifecycle → Repository preparation: prepares workspace
- Sandbox lifecycle → Sandbox providers: selects provider
- Coding agent graph → GitHub PR delivery: delivers changes
- Review and analysis graphs → GitHub PR delivery: reads PRs and posts review
- FastAPI application → Authorization and credentials: authorizes requests
- Execution middleware → LangSmith: traces runs
- Coding agent graph → MCP runtime: uses external tools
- Threads and run lifecycle → Analytics pipeline: emits product events
