# mssnzxm/deer-flow2 architecture

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

- Interactive diagram: https://gitdiagram.com/mssnzxm/deer-flow2
- Repository: https://github.com/mssnzxm/deer-flow2

## Overview

DeerFlow is a super-agent harness: users submit work through the web app, API, or messaging channels; runs orchestrate an agent and its tools, then stream results and retain state. The map preserves documented skills, subagents, memory, sandboxing, scheduling, and integrations. Some subsystems are present in the tree but unsampled; their links are omitted or marked unverified rather than inferred from names.

Main entry points: [`backend/packages/harness/deerflow/agents/lead_agent/agent.py`](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py) (Lead Agent), [`backend/app/gateway/app.py`](https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/gateway/app.py) (API Gateway), [`backend/app/gateway/services.py`](https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/gateway/services.py) (Run Services), [`backend/packages/harness/deerflow/runtime/runs/manager.py`](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py) (Run Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_web["Web App<br/>[page.tsx]"]
  node_client["Python Client<br/>[client.py]"]
  node_tui["Terminal Workbench<br/>[app.py]"]
end

subgraph group_gateway["Gateway and Channels"]
  node_gateway_app["API Gateway<br/>[app.py]"]
  node_auth["Authentication<br/>[auth_disabled.py]"]
  node_run_api["Run Services<br/>[services.py]"]
  node_channels["Messaging Channels<br/>[service.py]"]
  node_channel_dispatch["Channel Dispatch<br/>[manager.py]"]
end

subgraph group_execution["Agent Execution"]
  node_agent["Lead Agent<br/>[agent.py]"]
  node_subagents["Subagents<br/>[executor.py]"]
end

subgraph group_capabilities["Agent Capabilities"]
  node_skills["Skills and Tools<br/>[skill_storage.py]"]
  node_sandbox["Sandbox<br/>[sandbox.py]"]
  node_memory["Long-Term Memory<br/>[manager.py]"]
  node_search["Search Integrations<br/>[tools.py]"]
  node_uploads["File Uploads<br/>[manager.py]"]
end

subgraph group_state["State and Scheduling"]
  node_run_manager["Run Lifecycle<br/>[manager.py]"]
  node_run_store[("Run Store<br/>[base.py]")]
  node_persistence[("SQL Persistence<br/>[engine.py]")]
  node_user_context["User Context<br/>[user_context.py]"]
  node_scheduler["Scheduled Tasks<br/>[service.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -.->|"calls API"| node_gateway_app
node_client -.->|"calls API"| node_gateway_app
node_gateway_app -->|"configures auth"| node_auth
node_gateway_app -->|"mounts routes"| node_run_api
node_run_api -->|"invokes"| node_agent
node_run_api -.->|"manages runs"| node_run_manager
node_run_manager -->|"uses store"| node_run_store
node_channels -.->|"starts manager"| node_channel_dispatch
node_channel_dispatch -.->|"submits messages"| node_run_api
node_agent -.->|"delegates"| node_subagents
node_agent -.->|"uses skills"| node_skills
node_agent -.->|"executes safely"| node_sandbox
node_agent -.->|"uses memory"| node_memory
node_agent -.->|"searches"| node_search
node_run_api -.->|"handles uploads"| node_uploads
node_run_manager -->|"resolves identity"| node_user_context
node_gateway_app -.->|"initializes storage"| node_persistence
node_scheduler -.->|"starts runs"| node_run_manager
node_user -->|"uses"| node_tui

click node_web "https://github.com/mssnzxm/deer-flow2/blob/main/frontend/src/app/page.tsx"
click node_client "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/client.py"
click node_gateway_app "https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/gateway/app.py"
click node_auth "https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/gateway/auth_disabled.py"
click node_run_api "https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/gateway/services.py"
click node_channels "https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/channels/service.py"
click node_channel_dispatch "https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/channels/manager.py"
click node_agent "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py"
click node_subagents "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/subagents/executor.py"
click node_skills "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/skills/storage/skill_storage.py"
click node_sandbox "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/sandbox/sandbox.py"
click node_memory "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/agents/memory/manager.py"
click node_search "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/community/infoquest/tools.py"
click node_uploads "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/uploads/manager.py"
click node_run_manager "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py"
click node_run_store "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/runtime/runs/store/base.py"
click node_persistence "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/persistence/engine.py"
click node_user_context "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/runtime/user_context.py"
click node_scheduler "https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/scheduler/service.py"
click node_tui "https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/tui/app.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_web,node_client,node_tui,node_user toneBlue
class node_gateway_app,node_auth,node_run_api,node_channels,node_channel_dispatch toneAmber
class node_agent,node_subagents toneMint
class node_skills,node_sandbox,node_memory,node_search,node_uploads toneRose
class node_run_manager,node_run_store,node_persistence,node_user_context,node_scheduler toneIndigo
```

## Components

### User Interfaces

- [Web App](https://github.com/mssnzxm/deer-flow2/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Python Client](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/client.py): `backend/packages/harness/deerflow/client.py`
- [Terminal Workbench](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/tui/app.py): `backend/packages/harness/deerflow/tui/app.py`

### Gateway and Channels

- [API Gateway](https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/gateway/app.py): `backend/app/gateway/app.py`
- [Authentication](https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/gateway/auth_disabled.py): `backend/app/gateway/auth_disabled.py`
- [Run Services](https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/gateway/services.py): `backend/app/gateway/services.py`
- [Messaging Channels](https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/channels/service.py): `backend/app/channels/service.py`
- [Channel Dispatch](https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/channels/manager.py): `backend/app/channels/manager.py`

### Agent Execution

- [Lead Agent](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py): `backend/packages/harness/deerflow/agents/lead_agent/agent.py`
- [Subagents](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/subagents/executor.py): `backend/packages/harness/deerflow/subagents/executor.py`

### Agent Capabilities

- [Skills and Tools](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/skills/storage/skill_storage.py): `backend/packages/harness/deerflow/skills/storage/skill_storage.py`
- [Sandbox](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/sandbox/sandbox.py): `backend/packages/harness/deerflow/sandbox/sandbox.py`
- [Long-Term Memory](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/agents/memory/manager.py): `backend/packages/harness/deerflow/agents/memory/manager.py`
- [Search Integrations](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/community/infoquest/tools.py): `backend/packages/harness/deerflow/community/infoquest/tools.py`
- [File Uploads](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/uploads/manager.py): `backend/packages/harness/deerflow/uploads/manager.py`

### State and Scheduling

- [Run Lifecycle](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py): `backend/packages/harness/deerflow/runtime/runs/manager.py`
- [Run Store](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/runtime/runs/store/base.py): `backend/packages/harness/deerflow/runtime/runs/store/base.py`
- [SQL Persistence](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/persistence/engine.py): `backend/packages/harness/deerflow/persistence/engine.py`
- [User Context](https://github.com/mssnzxm/deer-flow2/blob/main/backend/packages/harness/deerflow/runtime/user_context.py): `backend/packages/harness/deerflow/runtime/user_context.py`
- [Scheduled Tasks](https://github.com/mssnzxm/deer-flow2/blob/main/backend/app/scheduler/service.py): `backend/app/scheduler/service.py`

### Other components

- **User**

## Connections

- User → Web App: uses (evidence: `README.md`)
- Web App → API Gateway: calls API
- Python Client → API Gateway: calls API
- API Gateway → Authentication: configures auth (evidence: `backend/app/gateway/app.py`)
- API Gateway → Run Services: mounts routes (evidence: `backend/app/gateway/app.py`)
- Run Services → Lead Agent: invokes (evidence: `backend/app/gateway/services.py`)
- Run Services → Run Lifecycle: manages runs
- Run Lifecycle → Run Store: uses store (evidence: `backend/packages/harness/deerflow/runtime/runs/manager.py`)
- Messaging Channels → Channel Dispatch: starts manager (evidence: `backend/app/channels/service.py`)
- Channel Dispatch → Run Services: submits messages
- Lead Agent → Subagents: delegates
- Lead Agent → Skills and Tools: uses skills
- Lead Agent → Sandbox: executes safely
- Lead Agent → Long-Term Memory: uses memory
- Lead Agent → Search Integrations: searches
- Run Services → File Uploads: handles uploads
- Run Lifecycle → User Context: resolves identity (evidence: `backend/packages/harness/deerflow/runtime/runs/manager.py`)
- API Gateway → SQL Persistence: initializes storage (evidence: `backend/app/gateway/app.py`)
- Scheduled Tasks → Run Lifecycle: starts runs
- User → Terminal Workbench: uses (evidence: `README.md`)