# sushmoyr/deeptutor architecture

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

- Interactive diagram: https://gitdiagram.com/sushmoyr/deeptutor
- Repository: https://github.com/sushmoyr/deeptutor

## Overview

1. **Repository shape**
   - DeepTutor is a monorepo with three user-facing surfaces: a **Python backend**, a **Next.js web app**, and a **Python CLI**.
   - The backend is the control plane: it owns orchestration, persistence, agent workflows, and provider access.
   - The web app is a presentation layer that talks to the backend over HTTP/WebSocket.
   - The CLI is a parallel entrypoint into the same capabilities and storage.

2. **Primary execution entrypoints**
   - `deeptutor.api.run_server` starts the backend API.
   - `deeptutor_cli/main.py` and `deeptutor/__main__.py` expose terminal access.
   - `web/app` is the browser UI.
   - Docker and `docker-compose*.yml` package the backend + frontend together for deployment.

3. **Core backend architecture**
   - `deeptutor/core`, `deeptutor/runtime`, and `deeptutor/app` define the shared execution model.
   - `core` contains protocol abstractions for capabilities, tools, streaming, tracing, and context.
   - `runtime` registers built-in capabilities and tools, then routes requests to the right implementation.
   - `app/facade.py` is the higher-level boundary that hides subsystem wiring from callers.

4. **Capability-oriented product design**
   - The repo is organized around named capabilities such as **chat**, **deep solve**, **deep research**, **deep question**, **math animator**, **co-writer**, **guide**, **notebook**, and **vision solver**.
   - Each capability has its own folder under `deeptutor/agents/*` and a matching contract in `deeptutor/capabilities/*`.
   - This is the main architectural boundary: the UI and CLI invoke capabilities, while each capability owns its own workflow, prompts, and request config.

5. **Agent workflows inside capabilities**
   - Capability folders contain multi-agent pipelines such as planner/solver/writer, research decomposition/reporting, question generation/follow-up, and math animation stages.
   - Prompt templates are stored per capability in `prompts/en` and `prompts/zh`, making language a first-class part of the workflow design.
   - Several capabilities are explicitly pipeline-based, not single-call LLM wrappers; they coordinate multiple model calls and intermediate artifacts.

6. **Shared service layer**
   - `deeptutor/services` is the reusable infrastructure behind all capabilities.
   - Major services include:
     - **LLM** provider abstraction and routing
     - **Embedding** clients and adapters
     - **RAG** parsing, chunking, indexing, retrieval, and pipeline selection
     - **Search** provider adapters for web/academic search
     - **Session** persistence and turn runtime
     - **Memory** storage
     - **Notebook** storage
     - **Settings/config** loading and provider runtime
   - This layer is the main dependency boundary between agent logic and external systems.

7. **External model and search integration**
   - `deeptutor/services/llm/providers` supports multiple model backends, with native provider adapters rather than a single proxy dependency.
   - `deeptutor/services/embedding/adapters` and `deeptutor/services/search/providers` do the same for embeddings and search.
   - The system is designed so capabilities choose services, and services choose providers; model/search vendors are therefore isolated behind adapter interfaces.

8. **Knowledge and RAG data flow**
   - Uploaded documents flow through `deeptutor/knowledge` and `deeptutor/services/rag`.
   - Parsers convert PDFs/Markdown/text into chunks, embedders create vectors, and indexers store them in knowledge-base directories.
   - Retrieval is then consumed by chat, research, co-writing, and guided learning.
   - The README’s “knowledge bases” and “notebooks” map to this persistent document-and-notes layer, which is shared across features.

9. **Persistent state and user workspace**
   - `deeptutor/services/session`, `memory`, `notebook`, and `knowledge` handle the main durable state.
   - The Docker docs show persistence under `data/user` and `data/knowledge_bases`; that matches the repo’s emphasis on saved sessions, memory summaries, notebooks, and KB indices.
   - Session state is central because multiple modes share one conversation thread and can resume later.

10. **Web backend API and realtime transport**
   - `deeptutor/api/routers/*` exposes capability endpoints plus management endpoints for sessions, settings, memory, knowledge, dashboard, and system state.
   - `unified_ws.py` and `api/utils/progress_broadcaster.py` indicate a realtime channel for streaming agent events, logs, and progress updates.
   - The browser app consumes both REST and websocket streams so long-running agent workflows can be visualized incrementally.

11. **Frontend structure**
   - `web/app/(workspace)` contains the main user workflows: chat, co-writer, guide, playground, and agent-specific pages.
   - `web/components` holds mode-specific UI pieces such as chat composer, trace panels, research configs, math animator viewer, quiz viewer, and notebook pickers.
   - `web/lib/*` wraps backend APIs, persistence, websocket streaming, markdown/LaTeX rendering, and client-side types.
   - This frontend is a stateful client, but the source of truth remains the backend services.

12. **TutorBot as a separate autonomous subsystem**
   - `deeptutor/tutorbot` is a distinct product line for persistent autonomous agents, separate from the main tutoring workspace.
   - It has its own agent loop, memory, skills, channels, providers, cron, heartbeat, and session storage.
   - TutorBots can connect to Slack, Discord, Telegram, email, and other channels, so this subsystem is more like a long-running agent platform than a UI feature.

13. **Tooling and extensibility model**
   - `deeptutor/tools` contains reusable tool implementations such as code execution, web search, paper search, RAG, reasoning, question extraction, and vision utilities.
   - `deeptutor/runtime/registry` and `deeptutor/tools/prompting` suggest a plugin-style architecture where tools and capabilities are registered, described, and surfaced dynamically.
   - This matters for the architecture diagram because tools are not hardwired into one mode; they are shared execution primitives used by many capabilities.

14. **Observability, safety, and ops boundaries**
   - `deeptutor/logging`, `events`, and `core/stream*` provide tracing, structured logging, and event propagation across agent runs.
   - There are utility layers for error handling, JSON parsing, token tracking, and circuit breaking, which are important because the system depends heavily on external model APIs.
   - Tests cover the backend, API routers, CLI, RAG, providers, and selected frontend logic, so the repo is organized around contract stability across those boundaries.

15. **How the main data path fits together**
   - A user action starts in the **web app** or **CLI**.
   - That request enters the **API/facade**, which selects a **capability**.
   - The capability orchestrates one or more **agents**, which call shared **services**.
   - Services talk to external **LLM/embedding/search providers** and persistent stores for **sessions, memory, notebooks, and knowledge bases**.
   - Results stream back through the API to the frontend or CLI, often with intermediate progress events rather than a single final response.

Main entry points: [`deeptutor/agents`](https://github.com/sushmoyr/deeptutor/tree/main/deeptutor/agents) (Agent workflows), [`deeptutor/api/routers`](https://github.com/sushmoyr/deeptutor/tree/main/deeptutor/api/routers) (API routers), [`web/lib/api.ts`](https://github.com/sushmoyr/deeptutor/blob/main/web/lib/api.ts) (Web client libs), [`deeptutor/tutorbot/agent/loop.py`](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/tutorbot/agent/loop.py) (Bot loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend control plane"]
  node_api_server(("API server<br/>entrypoint<br/>[run_server.py]"))
  node_api_routers["API routers<br/>http routes"]
  node_facade["App facade<br/>boundary<br/>[facade.py]"]
  node_runtime_orchestrator["Runtime orchestrator<br/>dispatch<br/>[orchestrator.py]"]
  node_cap_registry["Capability registry"]
  node_cap_contracts["Capability contracts<br/>protocols"]
  node_agent_workflows["Agent workflows<br/>pipelines"]
  node_core_protocols["Core protocols<br/>abstractions"]
  node_llm_service["LLM service<br/>model routing<br/>[factory.py]"]
  node_rag_service["RAG service<br/>retrieval<br/>[service.py]"]
  node_state_service[("State services<br/>persistence")]
  node_search_service["Search service<br/>adapters"]
  node_knowledge_store[("Knowledge layer<br/>documents<br/>[manager.py]")]
  node_realtime_bus{{"Realtime bus<br/>streaming<br/>[unified_ws.py]"}}
end

subgraph group_client["Client surfaces"]
  node_cli_entrypoints(("CLI entrypoints<br/>terminal<br/>[main.py]"))
  node_web_workspace["Web workspace<br/>nextjs ui"]
  node_web_client_libs["Web client libs<br/>api client<br/>[api.ts]"]
end

subgraph group_tutorbot["TutorBot platform"]
  node_tutorbot_manager["TutorBot manager<br/>autonomous agents<br/>[manager.py]"]
  node_tutorbot_loop["Bot loop<br/>agent runtime<br/>[loop.py]"]
end

subgraph group_ops["Ops and config"]
  node_deployment["Deployment<br/>packaging<br/>[docker-compose.yml]"]
  node_config_runtime["Config runtime<br/>settings<br/>[settings.py]"]
end

node_cli_entrypoints -->|"invoke"| node_facade
node_web_workspace -->|"uses"| node_web_client_libs
node_web_client_libs -->|"REST"| node_api_routers
node_web_client_libs -->|"ws"| node_realtime_bus
node_api_server -->|"hosts"| node_api_routers
node_api_routers -->|"delegates"| node_facade
node_facade -->|"orchestrates"| node_runtime_orchestrator
node_runtime_orchestrator -->|"resolves"| node_cap_registry
node_cap_registry -->|"binds"| node_cap_contracts
node_cap_contracts -->|"drives"| node_agent_workflows
node_agent_workflows -->|"uses"| node_core_protocols
node_agent_workflows -->|"calls"| node_llm_service
node_agent_workflows -->|"retrieves"| node_rag_service
node_agent_workflows -->|"persists"| node_state_service
node_agent_workflows -->|"searches"| node_search_service
node_rag_service -->|"indexes"| node_knowledge_store
node_state_service -->|"shares"| node_knowledge_store
node_llm_service -->|"configured by"| node_config_runtime
node_search_service -->|"configured by"| node_config_runtime
node_realtime_bus -->|"streams"| node_api_routers
node_tutorbot_manager -->|"runs"| node_tutorbot_loop
node_tutorbot_loop -->|"shares state"| node_state_service
node_tutorbot_loop -->|"configured by"| node_config_runtime
node_deployment -->|"packages"| node_api_server
node_deployment -->|"packages"| node_web_workspace

click node_api_server "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/api/run_server.py"
click node_api_routers "https://github.com/sushmoyr/deeptutor/tree/main/deeptutor/api/routers"
click node_facade "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/app/facade.py"
click node_runtime_orchestrator "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/runtime/orchestrator.py"
click node_cap_registry "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/runtime/registry/capability_registry.py"
click node_cap_contracts "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/capabilities/request_contracts.py"
click node_agent_workflows "https://github.com/sushmoyr/deeptutor/tree/main/deeptutor/agents"
click node_core_protocols "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/core/capability_protocol.py"
click node_llm_service "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/services/llm/factory.py"
click node_rag_service "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/services/rag/service.py"
click node_state_service "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/services/session/unified_session_manager.py"
click node_search_service "https://github.com/sushmoyr/deeptutor/tree/main/deeptutor/services/search"
click node_knowledge_store "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/knowledge/manager.py"
click node_cli_entrypoints "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor_cli/main.py"
click node_web_workspace "https://github.com/sushmoyr/deeptutor/tree/main/web/app/(workspace)"
click node_web_client_libs "https://github.com/sushmoyr/deeptutor/blob/main/web/lib/api.ts"
click node_realtime_bus "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/api/routers/unified_ws.py"
click node_tutorbot_manager "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/services/tutorbot/manager.py"
click node_tutorbot_loop "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/tutorbot/agent/loop.py"
click node_deployment "https://github.com/sushmoyr/deeptutor/blob/main/docker-compose.yml"
click node_config_runtime "https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/config/settings.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_api_server,node_api_routers,node_facade,node_runtime_orchestrator,node_cap_registry,node_cap_contracts,node_agent_workflows,node_core_protocols,node_llm_service,node_rag_service,node_state_service,node_search_service,node_knowledge_store,node_realtime_bus toneBlue
class node_cli_entrypoints,node_web_workspace,node_web_client_libs toneAmber
class node_tutorbot_manager,node_tutorbot_loop toneMint
class node_deployment,node_config_runtime toneRose
```

## Components

### Backend control plane

Python API, capability orchestration, shared services, and persistent state.

- [API server](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/api/run_server.py): entrypoint · Starts the backend service process. · `deeptutor/api/run_server.py`
- [API routers](https://github.com/sushmoyr/deeptutor/tree/main/deeptutor/api/routers): http routes · Capability, session, knowledge, settings, and websocket endpoints. · `deeptutor/api/routers`
- [App facade](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/app/facade.py): boundary · High-level entry boundary that hides subsystem wiring. · `deeptutor/app/facade.py`
- [Runtime orchestrator](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/runtime/orchestrator.py): dispatch · Coordinates mode selection and request routing. · `deeptutor/runtime/orchestrator.py`
- [Capability registry](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/runtime/registry/capability_registry.py): registry · Registers built-in capabilities and exposes them to the runtime. · `deeptutor/runtime/registry/capability_registry.py`
- [Capability contracts](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/capabilities/request_contracts.py): protocols · Shared capability request/response contracts and naming. · `deeptutor/capabilities/request_contracts.py`
- [Agent workflows](https://github.com/sushmoyr/deeptutor/tree/main/deeptutor/agents): pipelines · Capability-specific pipelines for chat, solve, research, guide, question, and math animation. · `deeptutor/agents`
- [Core protocols](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/core/capability_protocol.py): abstractions · Capability, tool, context, stream, and trace primitives. · `deeptutor/core/capability_protocol.py`
- [LLM service](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/services/llm/factory.py): model routing · Model client, provider selection, routing, and telemetry. · `deeptutor/services/llm/factory.py`
- [RAG service](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/services/rag/service.py): retrieval · Parsing, chunking, embedding, indexing, and retrieval pipelines. · `deeptutor/services/rag/service.py`
- [State services](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/services/session/unified_session_manager.py): persistence · Session, memory, notebook, and workspace persistence. · `deeptutor/services/session/unified_session_manager.py`
- [Search service](https://github.com/sushmoyr/deeptutor/tree/main/deeptutor/services/search): adapters · Web and academic search provider adapters behind one interface. · `deeptutor/services/search`
- [Knowledge layer](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/knowledge/manager.py): documents · Document ingestion and knowledge-base management shared by multiple capabilities. · `deeptutor/knowledge/manager.py`
- [Realtime bus](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/api/routers/unified_ws.py): streaming · Websocket progress, logs, and incremental agent events. · `deeptutor/api/routers/unified_ws.py`

### Client surfaces

Web app and CLI entrypoints that invoke backend capabilities.

- [CLI entrypoints](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor_cli/main.py): terminal · Terminal access to the same backend capabilities and storage. · `deeptutor_cli/main.py`
- [Web workspace](https://github.com/sushmoyr/deeptutor/tree/main/web/app/(workspace)): nextjs ui · Browser workspace for chat, guide, co-writer, notebook, and utility pages. · `web/app/(workspace)`
- [Web client libs](https://github.com/sushmoyr/deeptutor/blob/main/web/lib/api.ts): api client · REST, websocket, persistence, and rendering helpers used by the UI. · `web/lib/api.ts`

### TutorBot platform

Autonomous agent subsystem with its own loop, channels, and sessioning.

- [TutorBot manager](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/services/tutorbot/manager.py): autonomous agents · Separate persistent agent platform for long-running bots and sessions. · `deeptutor/services/tutorbot/manager.py`
- [Bot loop](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/tutorbot/agent/loop.py): agent runtime · Autonomous loop, memory, skills, cron, heartbeat, and channel delivery. · `deeptutor/tutorbot/agent/loop.py`

### Ops and config

Deployment packaging and runtime configuration.

- [Deployment](https://github.com/sushmoyr/deeptutor/blob/main/docker-compose.yml): packaging · Container and compose packaging for backend plus frontend. · `docker-compose.yml`
- [Config runtime](https://github.com/sushmoyr/deeptutor/blob/main/deeptutor/config/settings.py): settings · Shared settings, provider runtime, and environment loading. · `deeptutor/config/settings.py`

## Connections

- CLI entrypoints → App facade: invoke · CLI actions enter the same application boundary as the API.
- Web workspace → Web client libs: uses · The browser UI calls helper libraries for API and stream access.
- Web client libs → API routers: REST · Client libraries talk to backend HTTP endpoints.
- Web client libs → Realtime bus: ws · Client libraries consume live progress and event streams.
- API server → API routers: hosts · Server startup exposes the router surface.
- API routers → App facade: delegates · Routers hand capability requests to the application facade.
- App facade → Runtime orchestrator: orchestrates · Facade delegates mode and request routing to the runtime.
- Runtime orchestrator → Capability registry: resolves · The orchestrator looks up available capabilities.
- Capability registry → Capability contracts: binds · Registered capabilities conform to shared contracts.
- Capability contracts → Agent workflows: drives · Capability contracts map into capability-specific pipelines.
- Agent workflows → Core protocols: uses · Agents rely on shared context, tool, stream, and trace primitives.
- Agent workflows → LLM service: calls · Capability workflows execute model-backed reasoning steps.
- Agent workflows → RAG service: retrieves · Research, chat, co-writing, and guide flows use retrieval.
- Agent workflows → State services: persists · Workflows share sessions, memory, notebooks, and turn runtime.
- Agent workflows → Search service: searches · Research and answer flows can use web or academic search.
- RAG service → Knowledge layer: indexes · Documents are parsed and stored in persistent knowledge bases.
- State services → Knowledge layer: shares · Sessioned tutoring and notebook workflows reuse stored knowledge.
- LLM service → Config runtime: configured by · Provider choice and model behavior come from settings and runtime config.
- Search service → Config runtime: configured by · Search providers and keys are loaded from shared configuration.
- Realtime bus → API routers: streams · Websocket and progress broadcasting are exposed through API routes.
- TutorBot manager → Bot loop: runs · The manager coordinates autonomous bot execution.
- Bot loop → State services: shares state · TutorBots persist sessions and memory through shared storage patterns.
- Bot loop → Config runtime: configured by · Bot providers, channels, and runtime settings come from shared config.
- Deployment → API server: packages · Compose and container setup package the backend service.
- Deployment → Web workspace: packages · Deployment also includes the frontend app.
