# 2356222374/deer-flow architecture

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

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

## Overview

DeerFlow is a super-agent harness for research and other multi-step work, exposed through a web/API gateway and messaging channels. The principal workflow is a user request entering the gateway or a channel, becoming an agent run, and using skills, tools, memory, subagents, and sandboxes to produce a response or artifacts. The graph also preserves scheduled tasks, MCP tasks, and extension capabilities documented or represented in the repository. Some subsystem links are dashed because their implementation was not sampled; source-index references and the README support only the cited relationships.

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

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entrypoints"]
  node_gateway["API gateway<br/>[app.py]"]
  node_chat_routes["Conversation routes"]
  node_channels["Messaging channels<br/>[manager.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Lead agent<br/>[agent.py]"]
  node_agent_factory["Agent assembly<br/>[factory.py]"]
  node_middleware["Agent middleware"]
end

subgraph group_capabilities["Agent capabilities"]
  node_skills["Skills<br/>[skill_storage.py]"]
  node_memory["Long-term memory<br/>[manager.py]"]
  node_deermem[("DeerMem storage<br/>[storage.py]")]
  node_subagents["Subagents<br/>[batch_service.py]"]
  node_sandbox["Sandbox tools<br/>[aio_sandbox.py]"]
  node_search_tools["Search and web tools"]
  node_extensions["Extensions<br/>[manager.py]"]
end

subgraph group_operations["Runs and operations"]
  node_run_manager["Run manager<br/>[manager.py]"]
  node_run_store[("Run store<br/>[base.py]")]
  node_scheduler["Task scheduler<br/>[service.py]"]
  node_scheduled_routes["Scheduled task API<br/>[scheduled_tasks.py]"]
  node_mcp_tasks["MCP task service<br/>[service.py]"]
end

subgraph group_platform["Identity and persistence"]
  node_identity["Authentication<br/>[auth_disabled.py]"]
  node_database[("SQL database<br/>[engine.py]")]
end

node_user(("User"))
node_external_services{{"Model and tool providers"}}

node_user -->|"sends request"| node_gateway
node_user -.->|"sends message"| node_channels
node_gateway -->|"routes requests"| node_chat_routes
node_gateway -->|"configures auth"| node_identity
node_channels -->|"creates runs"| node_gateway
node_chat_routes -.->|"starts runs"| node_run_manager
node_gateway -.->|"initializes runtime"| node_run_manager
node_agent_factory -.->|"assembles"| node_agent
node_agent -.->|"uses"| node_middleware
node_agent -.->|"uses skills"| node_skills
node_agent -.->|"uses memory"| node_memory
node_memory -.->|"stores facts"| node_deermem
node_agent -.->|"delegates work"| node_subagents
node_agent -.->|"executes in"| node_sandbox
node_agent -.->|"invokes tools"| node_search_tools
node_agent -.->|"loads extensions"| node_extensions
node_agent -.->|"requests inference"| node_external_services
node_run_manager -->|"persists runs"| node_run_store
node_scheduled_routes -.->|"manages schedules"| node_scheduler
node_scheduler -->|"launches runs"| node_run_manager
node_gateway -->|"starts service"| node_mcp_tasks
node_mcp_tasks -->|"reads run state"| node_run_manager
node_gateway -.->|"initializes storage"| node_database
node_run_manager -.->|"uses persistence"| node_database

click node_gateway "https://github.com/2356222374/deer-flow/blob/main/backend/app/gateway/app.py"
click node_chat_routes "https://github.com/2356222374/deer-flow/tree/main/backend/app/gateway/routers"
click node_channels "https://github.com/2356222374/deer-flow/blob/main/backend/app/channels/manager.py"
click node_agent "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py"
click node_agent_factory "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/agents/factory.py"
click node_middleware "https://github.com/2356222374/deer-flow/tree/main/backend/packages/harness/deerflow/agents/middlewares"
click node_skills "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/skills/storage/skill_storage.py"
click node_memory "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/agents/memory/manager.py"
click node_deermem "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py"
click node_subagents "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/subagents/batch_service.py"
click node_sandbox "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/community/aio_sandbox/aio_sandbox.py"
click node_search_tools "https://github.com/2356222374/deer-flow/tree/main/backend/packages/harness/deerflow/community"
click node_extensions "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/extensions/manager.py"
click node_run_manager "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py"
click node_run_store "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/runtime/runs/store/base.py"
click node_scheduler "https://github.com/2356222374/deer-flow/blob/main/backend/app/scheduler/service.py"
click node_scheduled_routes "https://github.com/2356222374/deer-flow/blob/main/backend/app/gateway/routers/scheduled_tasks.py"
click node_mcp_tasks "https://github.com/2356222374/deer-flow/blob/main/backend/app/mcp_tasks/service.py"
click node_identity "https://github.com/2356222374/deer-flow/blob/main/backend/app/gateway/auth_disabled.py"
click node_database "https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/persistence/engine.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_chat_routes,node_channels,node_user toneBlue
class node_agent,node_agent_factory,node_middleware toneAmber
class node_skills,node_memory,node_deermem,node_subagents,node_sandbox,node_search_tools,node_extensions toneMint
class node_run_manager,node_run_store,node_scheduler,node_scheduled_routes,node_mcp_tasks toneRose
class node_identity,node_database,node_external_services toneIndigo
```

## Components

### User entrypoints

- [API gateway](https://github.com/2356222374/deer-flow/blob/main/backend/app/gateway/app.py): `backend/app/gateway/app.py`
- [Conversation routes](https://github.com/2356222374/deer-flow/tree/main/backend/app/gateway/routers): `backend/app/gateway/routers`
- [Messaging channels](https://github.com/2356222374/deer-flow/blob/main/backend/app/channels/manager.py): `backend/app/channels/manager.py`

### Agent runtime

- [Lead agent](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py): `backend/packages/harness/deerflow/agents/lead_agent/agent.py`
- [Agent assembly](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/agents/factory.py): `backend/packages/harness/deerflow/agents/factory.py`
- [Agent middleware](https://github.com/2356222374/deer-flow/tree/main/backend/packages/harness/deerflow/agents/middlewares): `backend/packages/harness/deerflow/agents/middlewares`

### Agent capabilities

- [Skills](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/skills/storage/skill_storage.py): `backend/packages/harness/deerflow/skills/storage/skill_storage.py`
- [Long-term memory](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/agents/memory/manager.py): `backend/packages/harness/deerflow/agents/memory/manager.py`
- [DeerMem storage](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py): `backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py`
- [Subagents](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/subagents/batch_service.py): `backend/packages/harness/deerflow/subagents/batch_service.py`
- [Sandbox tools](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/community/aio_sandbox/aio_sandbox.py): `backend/packages/harness/deerflow/community/aio_sandbox/aio_sandbox.py`
- [Search and web tools](https://github.com/2356222374/deer-flow/tree/main/backend/packages/harness/deerflow/community): `backend/packages/harness/deerflow/community`
- [Extensions](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/extensions/manager.py): `backend/packages/harness/deerflow/extensions/manager.py`

### Runs and operations

- [Run manager](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py): `backend/packages/harness/deerflow/runtime/runs/manager.py`
- [Run store](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/runtime/runs/store/base.py): `backend/packages/harness/deerflow/runtime/runs/store/base.py`
- [Task scheduler](https://github.com/2356222374/deer-flow/blob/main/backend/app/scheduler/service.py): `backend/app/scheduler/service.py`
- [Scheduled task API](https://github.com/2356222374/deer-flow/blob/main/backend/app/gateway/routers/scheduled_tasks.py): `backend/app/gateway/routers/scheduled_tasks.py`
- [MCP task service](https://github.com/2356222374/deer-flow/blob/main/backend/app/mcp_tasks/service.py): `backend/app/mcp_tasks/service.py`

### Identity and persistence

- [Authentication](https://github.com/2356222374/deer-flow/blob/main/backend/app/gateway/auth_disabled.py): `backend/app/gateway/auth_disabled.py`
- [SQL database](https://github.com/2356222374/deer-flow/blob/main/backend/packages/harness/deerflow/persistence/engine.py): `backend/packages/harness/deerflow/persistence/engine.py`

### Other components

- **User**
- **Model and tool providers**

## Connections

- User → API gateway: sends request (evidence: `README.md`)
- User → Messaging channels: sends message (evidence: `README.md`)
- API gateway → Conversation routes: routes requests (evidence: `backend/app/gateway/app.py`)
- API gateway → Authentication: configures auth (evidence: `backend/app/gateway/app.py`)
- Messaging channels → API gateway: creates runs (evidence: `backend/app/channels/manager.py`)
- Conversation routes → Run manager: starts runs
- API gateway → Run manager: initializes runtime
- Agent assembly → Lead agent: assembles
- Lead agent → Agent middleware: uses
- Lead agent → Skills: uses skills (evidence: `README.md`)
- Lead agent → Long-term memory: uses memory (evidence: `README.md`)
- Long-term memory → DeerMem storage: stores facts (evidence: `backend/packages/harness/deerflow/agents/memory/manager.py`)
- Lead agent → Subagents: delegates work (evidence: `README.md`)
- Lead agent → Sandbox tools: executes in (evidence: `README.md`)
- Lead agent → Search and web tools: invokes tools (evidence: `README.md`)
- Lead agent → Extensions: loads extensions (evidence: `README.md`)
- Lead agent → Model and tool providers: requests inference (evidence: `README.md`)
- Run manager → Run store: persists runs (evidence: `backend/packages/harness/deerflow/runtime/runs/manager.py`)
- Scheduled task API → Task scheduler: manages schedules (evidence: `backend/app/gateway/routers/scheduled_tasks.py`)
- Task scheduler → Run manager: launches runs (evidence: `backend/app/scheduler/service.py`)
- API gateway → MCP task service: starts service (evidence: `backend/app/gateway/app.py`)
- MCP task service → Run manager: reads run state (evidence: `backend/app/mcp_tasks/service.py`)
- API gateway → SQL database: initializes storage (evidence: `backend/app/gateway/app.py`)
- Run manager → SQL database: uses persistence (evidence: `backend/packages/harness/deerflow/persistence/engine.py`)