# DeerFlow Source Code Location: Complete Repository Structure Guide

> Find the DeerFlow source code easily within the bytedance/deer-flow repository. Discover the Python backend location in backend/src/ and the TypeScript frontend in frontend/.

- Repository: [Bytedance Inc./deer-flow](https://github.com/bytedance/deer-flow)
- Tags: repository-structure
- Published: 2026-03-08

---

**The DeerFlow source code is located in the `bytedance/deer-flow` GitHub repository, with the Python backend in `backend/src/` and the TypeScript frontend in `frontend/`.**

DeerFlow is ByteDance's open-source agentic AI framework designed for building complex research and task automation workflows. Understanding the DeerFlow source code location is essential for developers contributing to the project, debugging agent behavior, or extending its tool ecosystem. This guide provides a comprehensive map of the repository structure, from the FastAPI gateway implementation to the Next.js frontend components.

## DeerFlow Repository Structure Overview

The DeerFlow repository follows a monorepo pattern containing two distinct runtime environments:

| Component | Language | Description | Source Location |
|-----------|----------|-------------|-----------------|
| **Backend** | Python | Core agent engine, API gateway, tool implementations, sandbox execution, and memory system. | `backend/src/` |
| **Frontend** | TypeScript / React (Next.js) | Web UI for interacting with agents, visualizing artifacts, and managing configurations. | `frontend/` |

All source files are hosted under the repository root at `https://github.com/bytedance/deer-flow`.

## Backend Source Code Location (`backend/src/`)

The Python backend contains the core agentic logic and is organized into functional modules under `backend/src/`.

### Core Gateway and API (`backend/src/gateway/`)

The FastAPI application factory resides in [`backend/src/gateway/app.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/app.py). This module creates the main application instance, registers routers for models, skills, uploads, artifacts, and channels, and starts optional IM channel services.

Key entry points:
- **API Gateway**: [`backend/src/gateway/app.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/app.py) – `create_app()` function
- **Routers**: `backend/src/gateway/routers/` – Individual API endpoint definitions

### Embedded Python Client ([`backend/src/client.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py))

For programmatic interaction without running the HTTP server, DeerFlow provides `DeerFlowClient` in [`backend/src/client.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py). This class builds LangChain agents on-demand, streams events, and offers convenience methods for common operations.

```python
from src.client import DeerFlowClient

# Initialise client (reads config.yaml automatically)

client = DeerFlowClient()

# One-shot chat

response = client.chat("Summarize the key points of the 2023 AI trends report.")
print(response)

# Stream conversation (captures tool calls, artifacts, etc.)

for event in client.stream("Generate a slide deck about quantum computing."):
    print(event.type, event.data)

# List available models

print(client.list_models())

# Upload a PDF and convert it to markdown (auto-conversion)

upload_info = client.upload_files(thread_id="demo", files=["./reports/qc_overview.pdf"])
print(upload_info)

```

### Agent System (`backend/src/agents/`)

The agent orchestration logic is located in `backend/src/agents/`:

- **Lead Agent**: `backend/src/agents/lead_agent/` – Constructs the primary agent with middleware stack (title generation, sub-agent limits, image viewing, upload handling)
- **Memory**: `backend/src/agents/memory/` – Long-term memory implementation
- **Sub-agents**: `backend/src/subagents/` – Management of delegated task agents

### Tools and Sandbox (`backend/src/tools/` and `backend/src/sandbox/`)

Tool implementations reside in `backend/src/tools/`, including web search, file viewing, and presentation generation.

Isolated execution environments are managed under `backend/src/sandbox/`:
- **Providers**: Docker and local sandbox implementations
- **Middleware**: Execution wrappers for safe code running

### Configuration (`backend/src/config/`)

Configuration models using Pydantic are stored in `backend/src/config/`:
- [`backend/src/config/memory_config.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/config/memory_config.py) – Memory system settings
- [`backend/src/config/model_config.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/config/model_config.py) – LLM model configurations
- [`backend/src/config/sandbox_config.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/config/sandbox_config.py) – Sandbox execution parameters

## Frontend Source Code Location (`frontend/`)

The user interface is built with Next.js and TypeScript.

### Next.js Application Structure

The frontend entry point is [`frontend/pages/index.tsx`](https://github.com/bytedance/deer-flow/blob/main/frontend/pages/index.tsx). The application communicates with the backend gateway through the auto-generated OpenAPI client.

Key directories:
- `frontend/pages/` – Next.js page routes
- `frontend/components/` – React UI components
- `frontend/public/` – Static assets

To start the development server:

```bash
make dev          # starts backend

make frontend-dev # starts Next.js dev server on http://localhost:2026

```

## Key Configuration Files

At the repository root, [`config.example.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml) provides the default configuration template. This file defines models, sandbox mode, memory settings, and extension loading. The backend reads this configuration at startup to initialize the gateway, client, and agent systems.

## How to Navigate the DeerFlow Source Code

When exploring the repository:

1. **Start with the gateway** – [`backend/src/gateway/app.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/app.py) shows how all components wire together
2. **Check the client** – [`backend/src/client.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py) demonstrates high-level usage patterns
3. **Trace agent execution** – Begin at `backend/src/agents/lead_agent/` and follow through to `backend/src/tools/`
4. **Review tests** – `backend/tests/` contains examples of expected behavior for uploads, title generation, and sub-agent execution

## Summary

- The **DeerFlow source code** is hosted at `https://github.com/bytedance/deer-flow` as a monorepo
- **Backend code** resides in `backend/src/`, containing the FastAPI gateway ([`backend/src/gateway/app.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/app.py)), embedded client ([`backend/src/client.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py)), agent system (`backend/src/agents/`), and tools (`backend/src/tools/`)
- **Frontend code** is located in `frontend/`, built with Next.js and TypeScript, with the entry point at [`frontend/pages/index.tsx`](https://github.com/bytedance/deer-flow/blob/main/frontend/pages/index.tsx)
- **Configuration** is managed through [`config.example.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml) at the repository root and Pydantic models in `backend/src/config/`

## Frequently Asked Questions

### Where is the main entry point for the DeerFlow API?

The main entry point is [`backend/src/gateway/app.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/app.py), which contains the `create_app()` factory function. This module initializes the FastAPI application, registers routers for models, skills, uploads, and artifacts, and starts the HTTP server. You can start the gateway using `make dev` from the repository root.

### How do I find the DeerFlow agent implementation in the source code?

The agent implementation is split across several directories under `backend/src/`. The lead agent construction resides in `backend/src/agents/lead_agent/`, which composes middleware for title generation, sub-agent limits, and image viewing. Tool definitions are in `backend/src/tools/`, while sub-agent management is handled by `backend/src/subagents/`. The memory system is located at `backend/src/agents/memory/`.

### What is the difference between the backend and frontend source locations?

The **backend** (`backend/src/`) contains Python code for the core agent engine, API gateway, tool implementations, sandbox execution, and memory systems. The **frontend** (`frontend/`) contains TypeScript and React code built with Next.js, providing the web UI for interacting with agents. The backend exposes REST APIs that the frontend consumes, with the frontend entry point at [`frontend/pages/index.tsx`](https://github.com/bytedance/deer-flow/blob/main/frontend/pages/index.tsx).

### Where are DeerFlow configuration files stored?

Configuration files are primarily stored in two locations. The root directory contains [`config.example.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml), which serves as the default template for model settings, sandbox modes, memory configuration, and extensions. The `backend/src/config/` directory contains Pydantic-based Python modules like [`memory_config.py`](https://github.com/bytedance/deer-flow/blob/main/memory_config.py), [`model_config.py`](https://github.com/bytedance/deer-flow/blob/main/model_config.py), and [`sandbox_config.py`](https://github.com/bytedance/deer-flow/blob/main/sandbox_config.py) that define the configuration schemas used by the application at runtime.