# DeepTutor Project Structure: A Modular Agent-Native Architecture Guide

> Explore the DeepTutor project structure. Discover its modular agent-native architecture, layered design, and two-level registry system for tools and capabilities.

- Repository: [✨Data Intelligence Lab@HKU✨/DeepTutor](https://github.com/HKUDS/DeepTutor)
- Tags: architecture
- Published: 2026-04-08

---

**DeepTutor implements a layered, agent-native architecture that cleanly separates entry points, runtime orchestration, and extensibility through a two-level registry system managing tools and capabilities.**

The HKUDS/DeepTutor repository is an open-source educational AI platform engineered for flexibility and scale. Understanding the DeepTutor project structure reveals how the system isolates concerns between user interfaces, business logic, and execution primitives. This design enables seamless integration across CLI, WebSocket API, and Python SDK interfaces while maintaining a consistent internal execution model.

## High-Level Architectural Layers

The DeepTutor project structure follows a strict separation of concerns across four primary layers. At the top, **Entry Points** provide user-facing interfaces through the Typer-based CLI ([`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py)) and FastAPI server ([`deeptutor/api/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/api/main.py)). The **Orchestration Layer** contains the `ChatOrchestrator` class that routes incoming requests to appropriate processing pipelines. The **Runtime Layer** implements a two-level registry system distinguishing between atomic tools and complex capabilities. Finally, the **Extension Layer** supports self-contained plugins and domain-specific agents.

## Entry Points and Interface Layer

DeepTutor exposes three distinct interfaces that all funnel into the same core runtime.

### Command-Line Interface

The CLI is implemented using Typer in [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py), with subcommand modules located in `deeptutor_cli/*.py` (e.g., [`deeptutor_cli/chat.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/chat.py)). This entry point supports running capabilities directly, managing knowledge bases, and launching the web UI.

```bash
deeptutor run chat "Explain Fourier transform"

```

### WebSocket and HTTP API

The FastAPI application bootstrap resides in [`deeptutor/api/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/api/main.py). Individual capability endpoints are modularized under `deeptutor/api/routers/*.py`, such as [`deeptutor/api/routers/chat.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/api/routers/chat.py). The system supports both standard HTTP requests and persistent WebSocket connections at `/api/v1/ws` for streaming responses.

### Python SDK

Developers can import and invoke capabilities programmatically without using the CLI or API, accessing the same `ChatOrchestrator` and registry systems directly from Python code.

## The Orchestration Engine

At the heart of the DeepTutor project structure sits the **ChatOrchestrator**, defined in [`deeptutor/runtime/orchestrator.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/orchestrator.py). This class acts as the central traffic controller, receiving requests from any entry point and resolving them to the appropriate capability. The orchestrator manages the lifecycle of requests, coordinates streaming output, and ensures that execution contexts are properly initialized and passed downstream.

## Two-Level Registry System

DeepTutor distinguishes between atomic operations and complex workflows through a hierarchical registry model documented in the repository's [`AGENTS.md`](https://github.com/HKUDS/DeepTutor/blob/main/AGENTS.md).

### Level 1: Tool Registry

The **Tool Registry** ([`deeptutor/runtime/registry/tool_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/registry/tool_registry.py)) manages lightweight, single-function utilities that LLMs can invoke on demand. These include RAG retrieval, web search, and code execution primitives. Tools registered here inherit from `BaseTool` and execute discrete, stateless operations.

```python
from deeptutor.runtime.registry import tool_registry

search = tool_registry.get_tool("web_search")
result = await search.run(query="latest advances in quantum computing")
print(result)

```

### Level 2: Capability Registry

The **Capability Registry** ([`deeptutor/runtime/registry/capability_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/registry/capability_registry.py)) handles multi-step pipelines that combine tools, reasoning stages, and streaming output. Capabilities inherit from `BaseCapability` and include implementations like chat ([`deeptutor/capabilities/chat.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/capabilities/chat.py)) and deep-solve ([`deeptutor/capabilities/deep_solve.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/capabilities/deep_solve.py)). These represent high-level user-facing features that orchestrate multiple tools and internal events to produce comprehensive responses.

```json
{
  "type": "run_capability",
  "payload": {
    "name": "deep_solve",
    "input": "Solve x^2 = 4"
  }
}

```

## Core Runtime Infrastructure

The execution model relies on several primitives defined in the `deeptutor/core/` package.

### Streaming and Context Management

The **StreamBus** class ([`deeptutor/core/stream_bus.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/core/stream_bus.py)) provides an event-driven mechanism for streaming intermediate results, reasoning steps, and final outputs back to callers. This enables real-time feedback during long-running operations. The **UnifiedContext** class ([`deeptutor/core/context.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/core/context.py)) maintains execution state, user session data, and configuration that persists throughout a capability's lifecycle.

### Event System

Internal communication between components utilizes an event bus located in `deeptutor/events/`, decoupling the orchestrator from specific tool implementations and enabling asynchronous processing.

## Agents and Plugin Architecture

DeepTutor supports both built-in agents and third-party extensions.

### Domain-Specific Agents

Concrete agent implementations reside in `deeptutor/agents/`, including the **Vision Solver** (`deeptutor/agents/vision_solver/`) for image-to-text reasoning, the **Math Animator** (`deeptutor/agents/math_animator/`) for generating animated proofs, and the base abstraction in [`deeptutor/agents/base_agent.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/agents/base_agent.py).

### Plugin System

Playground extensions are self-contained feature packs stored in `deeptutor/plugins/<plugin_name>/`. Each plugin exposes its functionality through a [`manifest.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/manifest.yaml) file that declares available capabilities and configuration schemas. The `PluginLoader` class dynamically discovers and registers these capabilities at runtime.

```python
from deeptutor.plugins.loader import PluginLoader

loader = PluginLoader()
loader.load("deep_research")
deep_research = loader.get_capability("deep_research")
await deep_research.run(context, stream)

```

## Directory Structure

The physical layout of the HKUDS/DeepTutor repository reflects these architectural boundaries:

```

deeptutor/                 # Core library

├─ agents/                # Domain-specific agent implementations

├─ api/                   # FastAPI server and routers

├─ capabilities/          # High-level pipeline definitions (chat, deep_solve, etc.)

├─ config/                # Settings schema and defaults (settings.py)

├─ core/                  # Orchestration primitives (stream_bus.py, context.py)

├─ events/                # Internal event bus implementations

├─ plugins/               # Extension manifests and loaders

├─ runtime/               # Tool and capability registries

│  ├─ registry/
│  │  ├─ tool_registry.py
│  │  └─ capability_registry.py
│  └─ orchestrator.py
└─ services/              # Background processes and setup (setup/init.py)

deeptutor_cli/            # Typer-based CLI entry points

assets/                   # Static documentation and release assets

docs/                     # Markdown documentation

scripts/                  # Utility and migration scripts

tests/                    # Unit and integration tests

```

## Configuration and Services

Centralized configuration management occurs in [`deeptutor/config/settings.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/config/settings.py), handling LLM provider credentials, RAG pipeline parameters, and UI port assignments. Background initialization tasks, such as knowledge base setup and agent warm-up, are coordinated through [`deeptutor/services/setup/init.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/services/setup/init.py).

## Summary

- **DeepTutor project structure** organizes code into four distinct layers: Entry Points, Orchestration, Runtime, and Extensions.
- The **ChatOrchestrator** in [`deeptutor/runtime/orchestrator.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/orchestrator.py) serves as the central request router for all interfaces.
- A **two-level registry system** separates atomic **Tools** ([`tool_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/tool_registry.py)) from complex **Capabilities** ([`capability_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/capability_registry.py)).
- **StreamBus** and **UnifiedContext** in `deeptutor/core/` provide event-driven streaming and execution state management.
- The plugin architecture uses [`manifest.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/manifest.yaml) files for declarative capability registration.
- Built-in agents for vision processing and mathematical reasoning reside in `deeptutor/agents/`.

## Frequently Asked Questions

### What is the difference between Level 1 Tools and Level 2 Capabilities in DeepTutor?

**Level 1 Tools** are single-function utilities registered in [`deeptutor/runtime/registry/tool_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/registry/tool_registry.py) that perform discrete tasks like web searches or calculations. **Level 2 Capabilities** are multi-step pipelines defined in [`deeptutor/runtime/registry/capability_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/registry/capability_registry.py) that orchestrate tools, reasoning, and streaming output to solve complex user requests like deep-research or problem-solving.

### How does the ChatOrchestrator route requests?

The **ChatOrchestrator**, implemented in [`deeptutor/runtime/orchestrator.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/orchestrator.py), receives requests from the CLI, API, or SDK entry points. It resolves the requested capability name against the Capability Registry, initializes a **UnifiedContext**, and delegates execution to the appropriate pipeline while managing the **StreamBus** for real-time result streaming.

### How do I extend DeepTutor with custom functionality?

You can extend the system by creating a plugin directory under `deeptutor/plugins/<your_plugin>/` containing a [`manifest.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/manifest.yaml) file that declares new capabilities. Alternatively, register custom tools directly in [`deeptutor/runtime/registry/tool_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/registry/tool_registry.py) or capabilities in [`deeptutor/runtime/registry/capability_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/registry/capability_registry.py) for built-in extensions.

### Where is the FastAPI application defined?

The main FastAPI application bootstrap is located in [`deeptutor/api/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/api/main.py). Individual endpoint routers are modularized within `deeptutor/api/routers/*.py`, such as [`deeptutor/api/routers/chat.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/api/routers/chat.py), which handle specific capability endpoints and WebSocket connections.