# bytedance/deer-flow architecture

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

- Interactive diagram: https://gitdiagram.com/bytedance/deer-flow
- Repository: https://github.com/bytedance/deer-flow

## Overview

DeerFlow 2.0 is an extensible agent harness: users submit work through the application, which coordinates agent runs and can draw on skills, subagents, memory, and sandboxes. The README also documents web research, private knowledge retrieval, projects, chat archives, scheduled tasks, and external messaging channels. The graph preserves these product branches, but several implementation links are documented capabilities rather than sampled call sites; those edges are dashed where wiring is unverified.

Main entry points: [`backend/app/gateway/app.py`](https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/app.py) (API gateway), [`backend/packages/harness/deerflow/agents/lead_agent/agent.py`](https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py) (Lead agent), [`backend/packages/harness/deerflow/runtime/runs/manager.py`](https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py) (Run manager), [`backend/app/gateway/routers/threads.py`](https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/routers/threads.py) (Threads and runs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway and access"]
  node_gateway["API gateway<br/>[app.py]"]
  node_auth["Authentication"]
  node_threads["Threads and runs<br/>[threads.py]"]
end

subgraph group_agent["Agent execution"]
  node_run_manager["Run manager<br/>[manager.py]"]
  node_lead["Lead agent<br/>[agent.py]"]
  node_subagents["Subagents<br/>[service.py]"]
  node_memory["Long-term memory<br/>[manager.py]"]
end

subgraph group_knowledge["Knowledge and tools"]
  node_skills["Skills<br/>[skill_storage.py]"]
  node_sandbox["Sandbox execution"]
  node_web_research["Web research"]
  node_private_knowledge["Private knowledge<br/>[knowledge.py]"]
  node_mcp["MCP tools<br/>[service.py]"]
end

subgraph group_workspace["Workspace and integrations"]
  node_persistence[("Persistence<br/>[engine.py]")]
  node_projects["Projects and files<br/>[projects.py]"]
  node_artifacts["Artifacts<br/>[artifacts.py]"]
  node_extensions["Extensions<br/>[manager.py]"]
  node_channels["Messaging channels<br/>[manager.py]"]
end

subgraph group_operations["Background operations"]
  node_scheduler["Scheduled tasks<br/>[service.py]"]
end

node_user(("User"))

node_user -.->|"submits work"| node_gateway
node_gateway -->|"configures"| node_auth
node_gateway -->|"registers routes"| node_threads
node_threads -.->|"starts runs"| node_run_manager
node_run_manager -.->|"runs agent"| node_lead
node_lead -.->|"delegates work"| node_subagents
node_lead -.->|"uses memory"| node_memory
node_lead -.->|"uses skills"| node_skills
node_lead -.->|"uses sandbox"| node_sandbox
node_lead -.->|"researches web"| node_web_research
node_gateway -.->|"offers retrieval"| node_private_knowledge
node_gateway -.->|"enables MCP"| node_mcp
node_run_manager -.->|"persists runs"| node_persistence
node_gateway -.->|"offers projects"| node_projects
node_gateway -->|"registers routes"| node_artifacts
node_lead -.->|"supports extensions"| node_extensions
node_channels -.->|"dispatches messages"| node_gateway
node_scheduler -.->|"launches runs"| node_run_manager

click node_gateway "https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/app.py"
click node_auth "https://github.com/bytedance/deer-flow/tree/main/backend/app/gateway/auth"
click node_threads "https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/routers/threads.py"
click node_run_manager "https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py"
click node_lead "https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py"
click node_subagents "https://github.com/bytedance/deer-flow/blob/main/backend/app/subagent_batches/service.py"
click node_memory "https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/agents/memory/manager.py"
click node_skills "https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/skills/storage/skill_storage.py"
click node_sandbox "https://github.com/bytedance/deer-flow/tree/main/backend/packages/harness/deerflow/community/aio_sandbox"
click node_web_research "https://github.com/bytedance/deer-flow/tree/main/backend/packages/harness/deerflow/community"
click node_private_knowledge "https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/routers/knowledge.py"
click node_mcp "https://github.com/bytedance/deer-flow/blob/main/backend/app/mcp_tasks/service.py"
click node_persistence "https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/persistence/engine.py"
click node_projects "https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/routers/projects.py"
click node_artifacts "https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/routers/artifacts.py"
click node_extensions "https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/extensions/manager.py"
click node_channels "https://github.com/bytedance/deer-flow/blob/main/backend/app/channels/manager.py"
click node_scheduler "https://github.com/bytedance/deer-flow/blob/main/backend/app/scheduler/service.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_gateway,node_auth,node_threads,node_user toneBlue
class node_run_manager,node_lead,node_subagents,node_memory toneAmber
class node_skills,node_sandbox,node_web_research,node_private_knowledge,node_mcp toneMint
class node_persistence,node_projects,node_artifacts,node_extensions,node_channels toneRose
class node_scheduler toneIndigo
```

## Components

### Gateway and access

- [API gateway](https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/app.py): `backend/app/gateway/app.py`
- [Authentication](https://github.com/bytedance/deer-flow/tree/main/backend/app/gateway/auth): `backend/app/gateway/auth`
- [Threads and runs](https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/routers/threads.py): `backend/app/gateway/routers/threads.py`

### Agent execution

- [Run manager](https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py): `backend/packages/harness/deerflow/runtime/runs/manager.py`
- [Lead agent](https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py): `backend/packages/harness/deerflow/agents/lead_agent/agent.py`
- [Subagents](https://github.com/bytedance/deer-flow/blob/main/backend/app/subagent_batches/service.py): `backend/app/subagent_batches/service.py`
- [Long-term memory](https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/agents/memory/manager.py): `backend/packages/harness/deerflow/agents/memory/manager.py`

### Knowledge and tools

- [Skills](https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/skills/storage/skill_storage.py): `backend/packages/harness/deerflow/skills/storage/skill_storage.py`
- [Sandbox execution](https://github.com/bytedance/deer-flow/tree/main/backend/packages/harness/deerflow/community/aio_sandbox): `backend/packages/harness/deerflow/community/aio_sandbox`
- [Web research](https://github.com/bytedance/deer-flow/tree/main/backend/packages/harness/deerflow/community): `backend/packages/harness/deerflow/community`
- [Private knowledge](https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/routers/knowledge.py): `backend/app/gateway/routers/knowledge.py`
- [MCP tools](https://github.com/bytedance/deer-flow/blob/main/backend/app/mcp_tasks/service.py): `backend/app/mcp_tasks/service.py`

### Workspace and integrations

- [Persistence](https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/persistence/engine.py): `backend/packages/harness/deerflow/persistence/engine.py`
- [Projects and files](https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/routers/projects.py): `backend/app/gateway/routers/projects.py`
- [Artifacts](https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/routers/artifacts.py): `backend/app/gateway/routers/artifacts.py`
- [Extensions](https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/extensions/manager.py): `backend/packages/harness/deerflow/extensions/manager.py`
- [Messaging channels](https://github.com/bytedance/deer-flow/blob/main/backend/app/channels/manager.py): `backend/app/channels/manager.py`

### Background operations

- [Scheduled tasks](https://github.com/bytedance/deer-flow/blob/main/backend/app/scheduler/service.py): `backend/app/scheduler/service.py`

### Other components

- **User**

## Connections

- User → API gateway: submits work (evidence: `README.md`)
- API gateway → Authentication: configures (evidence: `backend/app/gateway/app.py`)
- API gateway → Threads and runs: registers routes (evidence: `backend/app/gateway/app.py`)
- Threads and runs → Run manager: starts runs
- Run manager → Lead agent: runs agent
- Lead agent → Subagents: delegates work (evidence: `README.md`)
- Lead agent → Long-term memory: uses memory (evidence: `README.md`)
- Lead agent → Skills: uses skills (evidence: `README.md`)
- Lead agent → Sandbox execution: uses sandbox (evidence: `README.md`)
- Lead agent → Web research: researches web (evidence: `README.md`)
- API gateway → Private knowledge: offers retrieval (evidence: `README.md`)
- API gateway → MCP tools: enables MCP (evidence: `README.md`)
- Run manager → Persistence: persists runs (evidence: `backend/packages/harness/deerflow/runtime/runs/manager.py`)
- API gateway → Projects and files: offers projects (evidence: `README.md`)
- API gateway → Artifacts: registers routes (evidence: `backend/app/gateway/app.py`)
- Lead agent → Extensions: supports extensions (evidence: `README.md`)
- Messaging channels → API gateway: dispatches messages (evidence: `backend/app/channels/manager.py`)
- Scheduled tasks → Run manager: launches runs (evidence: `backend/app/scheduler/service.py`)
