# phessophissy/deer-flow architecture

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

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

## Overview

DeerFlow is a super-agent harness exposed through a web API and workspace. Users submit requests through the frontend or connected messaging channels; the Gateway manages runs, whose harness can use models, sub-agents, tools, memory, skills, and sandboxes, then returns results. The graph preserves documented capabilities and the sampled Gateway, run, channel, storage, and configuration layers. Several feature implementations were not sampled, so those subsystem paths and links are limited to what the tree or README supports.

Main entry points: [`backend/packages/harness/deerflow/agents/lead_agent/agent.py`](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py) (Agent Harness), [`backend/app/gateway/app.py`](https://github.com/phessophissy/deer-flow/blob/main/backend/app/gateway/app.py) (API Gateway), [`backend/packages/harness/deerflow/runtime/runs/manager.py`](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py) (Run Manager), [`backend/packages/harness/deerflow/skills/storage/skill_storage.py`](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/skills/storage/skill_storage.py) (Extensible Skills)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User Access"]
  node_frontend["Web Workspace"]
  node_gateway["API Gateway<br/>[app.py]"]
  node_auth["Authentication<br/>[auth_disabled.py]"]
  node_channels["Messaging Channels<br/>[service.py]"]
end

subgraph group_execution["Agent Execution"]
  node_api_services["Run Services<br/>[services.py]"]
  node_run_manager["Run Manager<br/>[manager.py]"]
  node_agent["Agent Harness<br/>[agent.py]"]
  node_channel_manager["Message Dispatch<br/>[manager.py]"]
  node_scheduler["Scheduled Tasks<br/>[service.py]"]
end

subgraph group_capabilities["Agent Capabilities"]
  node_skills["Extensible Skills<br/>[skill_storage.py]"]
  node_subagents["Sub-agents"]
  node_memory["Long-term Memory<br/>[manager.py]"]
  node_sandbox["Sandbox Tools<br/>[sandbox.py]"]
  node_mcp["MCP Tools<br/>[tools.py]"]
  node_models["Model Providers<br/>[factory.py]"]
end

subgraph group_state["State and Persistence"]
  node_skill_files["Skill Files"]
  node_database[("Application Database<br/>[engine.py]")]
  node_config["Runtime Configuration<br/>[app_config.py]"]
  node_paths["Runtime Paths<br/>[paths.py]"]
end

node_user(("User"))
node_external_messaging(("Messaging Platforms"))
node_external_models(("Model APIs"))

node_user -.->|"submits requests"| node_frontend
node_frontend -.->|"calls API"| node_gateway
node_gateway -->|"authenticates"| node_auth
node_gateway -->|"routes requests"| node_api_services
node_api_services -->|"manages runs"| node_run_manager
node_run_manager -.->|"runs agent"| node_agent
node_agent -.->|"uses skills"| node_skills
node_agent -.->|"delegates work"| node_subagents
node_agent -.->|"uses memory"| node_memory
node_agent -.->|"executes tools"| node_sandbox
node_agent -.->|"uses tools"| node_mcp
node_agent -.->|"queries models"| node_models
node_models -.->|"sends prompts"| node_external_models
node_skills -->|"reads and writes"| node_skill_files
node_gateway -.->|"starts service"| node_channels
node_channels -.->|"dispatches messages"| node_channel_manager
node_external_messaging -.->|"sends messages"| node_channels
node_channel_manager -.->|"launches runs"| node_run_manager
node_scheduler -.->|"launches scheduled runs"| node_run_manager
node_gateway -->|"initializes storage"| node_database
node_database -->|"reads database settings"| node_config
node_skills -->|"resolves skill paths"| node_paths
node_config -.->|"configures directories"| node_paths

click node_frontend "https://github.com/phessophissy/deer-flow/tree/main/frontend/src/app"
click node_gateway "https://github.com/phessophissy/deer-flow/blob/main/backend/app/gateway/app.py"
click node_auth "https://github.com/phessophissy/deer-flow/blob/main/backend/app/gateway/auth_disabled.py"
click node_api_services "https://github.com/phessophissy/deer-flow/blob/main/backend/app/gateway/services.py"
click node_run_manager "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py"
click node_agent "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py"
click node_channels "https://github.com/phessophissy/deer-flow/blob/main/backend/app/channels/service.py"
click node_channel_manager "https://github.com/phessophissy/deer-flow/blob/main/backend/app/channels/manager.py"
click node_scheduler "https://github.com/phessophissy/deer-flow/blob/main/backend/app/scheduler/service.py"
click node_skills "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/skills/storage/skill_storage.py"
click node_subagents "https://github.com/phessophissy/deer-flow/tree/main/backend/packages/harness/deerflow/agents"
click node_memory "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/agents/memory/manager.py"
click node_sandbox "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/sandbox/sandbox.py"
click node_mcp "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/mcp/tools.py"
click node_models "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/models/factory.py"
click node_skill_files "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/skills/storage/user_scoped_skill_storage.py"
click node_database "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/persistence/engine.py"
click node_config "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/config/app_config.py"
click node_paths "https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/config/paths.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_frontend,node_gateway,node_auth,node_channels,node_user toneBlue
class node_api_services,node_run_manager,node_agent,node_channel_manager,node_scheduler toneAmber
class node_skills,node_subagents,node_memory,node_sandbox,node_mcp,node_models,node_external_models toneMint
class node_skill_files,node_database,node_config,node_paths toneRose
class node_external_messaging toneIndigo
```

## Components

### User Access

- [Web Workspace](https://github.com/phessophissy/deer-flow/tree/main/frontend/src/app): `frontend/src/app`
- [API Gateway](https://github.com/phessophissy/deer-flow/blob/main/backend/app/gateway/app.py): `backend/app/gateway/app.py`
- [Authentication](https://github.com/phessophissy/deer-flow/blob/main/backend/app/gateway/auth_disabled.py): `backend/app/gateway/auth_disabled.py`
- [Messaging Channels](https://github.com/phessophissy/deer-flow/blob/main/backend/app/channels/service.py): `backend/app/channels/service.py`

### Agent Execution

- [Run Services](https://github.com/phessophissy/deer-flow/blob/main/backend/app/gateway/services.py): `backend/app/gateway/services.py`
- [Run Manager](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/runtime/runs/manager.py): `backend/packages/harness/deerflow/runtime/runs/manager.py`
- [Agent Harness](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py): `backend/packages/harness/deerflow/agents/lead_agent/agent.py`
- [Message Dispatch](https://github.com/phessophissy/deer-flow/blob/main/backend/app/channels/manager.py): `backend/app/channels/manager.py`
- [Scheduled Tasks](https://github.com/phessophissy/deer-flow/blob/main/backend/app/scheduler/service.py): `backend/app/scheduler/service.py`

### Agent Capabilities

- [Extensible Skills](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/skills/storage/skill_storage.py): `backend/packages/harness/deerflow/skills/storage/skill_storage.py`
- [Sub-agents](https://github.com/phessophissy/deer-flow/tree/main/backend/packages/harness/deerflow/agents): `backend/packages/harness/deerflow/agents`
- [Long-term Memory](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/agents/memory/manager.py): `backend/packages/harness/deerflow/agents/memory/manager.py`
- [Sandbox Tools](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/sandbox/sandbox.py): `backend/packages/harness/deerflow/sandbox/sandbox.py`
- [MCP Tools](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/mcp/tools.py): `backend/packages/harness/deerflow/mcp/tools.py`
- [Model Providers](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/models/factory.py): `backend/packages/harness/deerflow/models/factory.py`

### State and Persistence

- [Skill Files](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/skills/storage/user_scoped_skill_storage.py): `backend/packages/harness/deerflow/skills/storage/user_scoped_skill_storage.py`
- [Application Database](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/persistence/engine.py): `backend/packages/harness/deerflow/persistence/engine.py`
- [Runtime Configuration](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/config/app_config.py): `backend/packages/harness/deerflow/config/app_config.py`
- [Runtime Paths](https://github.com/phessophissy/deer-flow/blob/main/backend/packages/harness/deerflow/config/paths.py): `backend/packages/harness/deerflow/config/paths.py`

### Other components

- **User**
- **Messaging Platforms**
- **Model APIs**

## Connections

- User → Web Workspace: submits requests (evidence: `README.md`)
- Web Workspace → API Gateway: calls API (evidence: `README.md`)
- API Gateway → Authentication: authenticates (evidence: `backend/app/gateway/app.py`)
- API Gateway → Run Services: routes requests (evidence: `backend/app/gateway/app.py`)
- Run Services → Run Manager: manages runs (evidence: `backend/app/gateway/services.py`)
- Run Manager → Agent Harness: runs agent
- Agent Harness → Extensible Skills: uses skills (evidence: `README.md`)
- Agent Harness → Sub-agents: delegates work (evidence: `README.md`)
- Agent Harness → Long-term Memory: uses memory (evidence: `README.md`)
- Agent Harness → Sandbox Tools: executes tools (evidence: `README.md`)
- Agent Harness → MCP Tools: uses tools (evidence: `README.md`)
- Agent Harness → Model Providers: queries models (evidence: `README.md`)
- Model Providers → Model APIs: sends prompts (evidence: `README.md`)
- Extensible Skills → Skill Files: reads and writes (evidence: `backend/packages/harness/deerflow/skills/storage/user_scoped_skill_storage.py`)
- API Gateway → Messaging Channels: starts service (evidence: `backend/app/gateway/app.py`)
- Messaging Channels → Message Dispatch: dispatches messages (evidence: `backend/app/channels/service.py`)
- Messaging Platforms → Messaging Channels: sends messages (evidence: `README.md`)
- Message Dispatch → Run Manager: launches runs (evidence: `backend/app/channels/manager.py`)
- Scheduled Tasks → Run Manager: launches scheduled runs (evidence: `backend/app/scheduler/service.py`)
- API Gateway → Application Database: initializes storage (evidence: `backend/app/gateway/app.py`)
- Application Database → Runtime Configuration: reads database settings (evidence: `backend/packages/harness/deerflow/persistence/engine.py`)
- Extensible Skills → Runtime Paths: resolves skill paths (evidence: `backend/packages/harness/deerflow/skills/storage/user_scoped_skill_storage.py`)
- Runtime Configuration → Runtime Paths: configures directories
