# Programming Languages Used in DeepTutor: Python Backend and TypeScript Frontend Architecture

> Discover the programming languages powering DeepTutor. Explore its Python backend for AI and TypeScript frontend for seamless user experiences.

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

---

**DeepTutor utilizes a dual-language architecture that pairs a Python-based backend for AI orchestration with a TypeScript/React frontend for real-time user interactions.**

DeepTutor is an agent-native learning companion developed by HKUDS that leverages a sophisticated dual-language stack to deliver AI-driven tutoring capabilities. Understanding the programming languages used in DeepTutor reveals how the project strategically separates concerns between its AI engine and user interface. The codebase combines Python for backend intelligence with TypeScript for frontend interactivity, connected via strongly-typed WebSocket protocols that enable seamless language-agnostic streaming.

## Python Backend: Core Engine and CLI

The Python layer implements the agent-native runtime, LLM orchestration, and command-line interface that power DeepTutor's educational AI capabilities.

### Orchestration and Runtime Logic

At the heart of the Python backend lies the orchestration system defined in [`deeptutor/runtime/orchestrator.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/orchestrator.py). This module receives turn requests and constructs a `UnifiedContext` object (defined in [`deeptutor/core/context.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/core/context.py)) that maintains conversation state and attachments. The orchestrator dispatches requests through the **ToolRegistry** and **CapabilityRegistry**, where each capability (such as `deep_solve` or `deep_question`) extends `BaseCapability` and executes as an async coroutine.

### Command Line Interface

The CLI entry point resides in [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py), which utilizes the `typer` library to expose capabilities directly to developers. This interface allows terminal invocation of the same AI functions available through the web API, making the system accessible for scripting and automation without launching the frontend.

```python

# Run a deep-solve capability from the terminal

# (equivalent to: deeptutor run deep_solve "Solve x^2 = 4")

from deeptutor_cli.main import run_capability
from deeptutor_cli.common import build_turn_request

request = build_turn_request(
    content="Solve x^2 = 4",
    capability="deep_solve",
    session_id=None,
    tools=[],
    knowledge_bases=[],
    language="en",
)

run_capability(request=request, fmt="rich")

```

## TypeScript Frontend: Real-Time Web Interface

The frontend layer employs TypeScript with React to provide a responsive, interactive learning environment that communicates with the Python backend via WebSockets.

### Typed WebSocket Client

The `UnifiedWSClient` class in [`web/lib/unified-ws.ts`](https://github.com/HKUDS/DeepTutor/blob/main/web/lib/unified-ws.ts) implements a strongly-typed WebSocket client that mirrors Python's `StreamEvent` protocol. This client handles the `/api/v1/ws` endpoint, processing event types including `stage_start`, `content`, `tool_call`, and `result` to drive real-time UI updates without page refreshes.

### React Components and Visualization

Built on **Next.js 16** and **React 19** as declared in [`web/package.json`](https://github.com/HKUDS/DeepTutor/blob/main/web/package.json), the frontend under `web/app/` renders progressive responses using libraries like `rehype-katex` for mathematical notation and `cytoscape` for interactive visualizations. The TypeScript type system ensures that messages exchanged with the Python backend maintain strict schema consistency.

```typescript
import { UnifiedWSClient, StreamEvent } from "./unified-ws";

const client = new UnifiedWSClient((ev: StreamEvent) => {
  console.log(`⏳ ${ev.type}: ${ev.content}`);
});

client.connect();

// Start a turn asking the model to explain Fourier transform
client.send({
  type: "start_turn",
  content: "Explain Fourier transform",
  capability: "deep_question",
  tools: [],            // optional tool list
  language: "en",
});

```

## Supporting Languages and Configuration

Beyond the core Python and TypeScript components, DeepTutor incorporates auxiliary languages for tooling and infrastructure. **Shell (Bash)** scripts in the `scripts/` directory handle installation checks (such as [`scripts/check_install.py`](https://github.com/HKUDS/DeepTutor/blob/main/scripts/check_install.py) invoked by shell wrappers) and CI pipeline automation. **JSON** in [`web/package.json`](https://github.com/HKUDS/DeepTutor/blob/main/web/package.json) manages Node.js dependencies, while **YAML** in [`docker-compose.yml`](https://github.com/HKUDS/DeepTutor/blob/main/docker-compose.yml) defines container orchestration for both the Python server and Node-based web UI.

## Summary

- **Python** powers the backend orchestration, CLI ([`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py)), and AI capabilities through async coroutines and registry patterns.
- **TypeScript** drives the frontend via `UnifiedWSClient` in [`web/lib/unified-ws.ts`](https://github.com/HKUDS/DeepTutor/blob/main/web/lib/unified-ws.ts), providing typed WebSocket communication with React components.
- The architecture relies on **JSON** and **YAML** for configuration, plus Shell scripts for DevOps automation.
- Both layers communicate through a shared protocol over FastAPI WebSockets, enabling real-time streaming of educational content.

## Frequently Asked Questions

### Is DeepTutor written entirely in Python?

No, DeepTutor is not a single-language project. While the AI engine, orchestration logic in [`deeptutor/runtime/orchestrator.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/orchestrator.py), and CLI are implemented in Python, the interactive web interface is built with TypeScript and React. This dual-language approach allows the backend to focus on AI processing while the frontend handles responsive user interactions.

### What framework does DeepTutor use for its frontend?

The frontend utilizes Next.js 16 with React 19, as specified in [`web/package.json`](https://github.com/HKUDS/DeepTutor/blob/main/web/package.json). This setup supports server-side rendering capabilities and integrates with the TypeScript WebSocket client for real-time bidirectional communication with the Python backend.

### How do Python and TypeScript communicate in DeepTutor?

The languages communicate via a FastAPI WebSocket endpoint (`/api/v1/ws`) exposed by the Python server. The TypeScript frontend uses the `UnifiedWSClient` class to establish a typed connection, serializing JSON messages that mirror Python's `StreamEvent` dataclasses for seamless real-time streaming of LLM-driven interactions.

### Can I run DeepTutor capabilities without the web interface?

Yes, the Python CLI in [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py) allows direct invocation of capabilities from the terminal using the `typer` library. This enables developers to execute AI functions like `deep_solve` or `deep_question` through command-line arguments without launching the TypeScript frontend or WebSocket server.