Skip to main content
DeerFlow is built on a multi-service architecture that combines LangGraph for agent orchestration, FastAPI for REST APIs, and Next.js for the user interface.

​
System Overview

The system consists of four main components: 
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Frontend  │────▶│    Nginx     │◀────│   Gateway   │
│  (Port 3000)│     │  (Port 2026) │     │  API (8001) │
└─────────────┘     └──────┬───────┘     └─────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  LangGraph   │
                    │ Server (2024)│
                    └──────────────┘

LangGraph Server

Agent runtime and workflow execution engine (port 2024)

Gateway API

REST API for configuration and management (port 8001)

Frontend

Next.js web interface (port 3000)

Nginx

Unified reverse proxy entry point (port 2026)

​
LangGraph Server

The LangGraph Server is the core of DeerFlow, running the agent graph and managing execution. Port: 2024 Responsibilities:
  • Agent graph execution with middleware chain
  • Thread state management and checkpointing
  • Tool execution and sub-agent orchestration
  • Real-time streaming via Server-Sent Events (SSE)
Configuration: backend/langgraph.json 
{
  "graphs": {
    "lead_agent": "./src/agents/lead_agent/agent.py:make_lead_agent"
  },
  "store": {
    "class": "langgraph.store.memory:InMemoryStore"
  }
}
The LangGraph Server uses the official LangGraph platform for agent orchestration.

​
Gateway API

The Gateway API provides REST endpoints for configuration and system management. Port: 8001 Endpoints:
  • /api/models - Model configuration
  • /api/skills - Skills management
  • /api/mcp - MCP server configuration
  • /api/memory - Memory system access
  • /api/threads/{id}/uploads - File uploads
  • /api/threads/{id}/artifacts - Artifact serving
  • /health - Health check
Technology: FastAPI with Pydantic validation

Gateway API Reference

View complete API documentation

​
Frontend

The frontend is a Next.js application providing the chat interface and system configuration UI. Port: 3000 (accessed via Nginx on 2026) Key Features:
  • Real-time chat with streaming responses
  • Thread management and history
  • File upload interface
  • Model and skill configuration
  • Artifact preview and download
Technology Stack:
  • Next.js 16 with App Router
  • React 19
  • TanStack Query for state management
  • Tailwind CSS for styling

​
Nginx Reverse Proxy

Nginx acts as the unified entry point, routing requests to the appropriate backend services. Port: 2026 (default entry point) Routing:
  • /api/langgraph/* → LangGraph Server (2024)
  • /api/* → Gateway API (8001)
  • /* → Frontend (3000)
Benefits:
  • Single port access for all services
  • SSL/TLS termination
  • Load balancing capabilities
  • Static asset serving

​
Data Flow

​
Chat Message Flow

  1. User sends message via Frontend
  2. Frontend calls LangGraph Server via Nginx
  3. LangGraph Server processes message through middleware chain
  4. Agent executes with tools and sub-agents
  5. Streaming response sent back via SSE
  6. Frontend renders response in real-time

​
Configuration Flow

  1. User updates configuration via Frontend
  2. Frontend calls Gateway API via Nginx
  3. Gateway updates config.yaml or extensions_config.json
  4. LangGraph Server detects changes via file mtime
  5. Configuration reloaded on next request

​
Thread Isolation

Each conversation thread operates in isolation:
  • State: Separate ThreadState per thread
  • Filesystem: Thread-specific directories in sandbox
  • Memory: Thread context stored in checkpoints
  • Uploads: Files isolated to thread directory
Physical Structure: 
backend/.deer-flow/threads/
├── thread-abc123/
│   └── user-data/
│       ├── workspace/     # Agent working directory
│       ├── uploads/       # User uploaded files
│       └── outputs/       # Agent output files
└── thread-xyz789/
    └── user-data/
        ├── workspace/
        ├── uploads/
        └── outputs/

​
Deployment Modes

DeerFlow supports multiple deployment configurations:
All services run directly on the host machine:
make dev
  • LangGraph Server: localhost:2024
  • Gateway API: localhost:8001
  • Frontend: localhost:3000
  • Nginx: localhost:2026

​
Next Steps

Agent System

Learn about the lead agent and middleware chain

Sandbox

Understand sandbox execution and isolation

Skills

Explore the skills system

Deployment

Deploy DeerFlow to production

Build docs developers (and LLMs) love

Get started for freeTalk to us