How sushmoyr/deeptutor works
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: agents Agent workflows · routers API routers · api.ts Web client libs · loop.py Bot loop
Components 21
Backend control plane
Python API, capability orchestration, shared services, and persistent state.
- API server · Starts the backend service process.
deeptutor/api/run_server.py - API routers · Capability, session, knowledge, settings, and websocket endpoints.
deeptutor/api/routers - App facade · High-level entry boundary that hides subsystem wiring.
deeptutor/app/facade.py - Runtime orchestrator · Coordinates mode selection and request routing.
deeptutor/runtime/orchestrator.py - Capability registry · Registers built-in capabilities and exposes them to the runtime.
deeptutor/runtime/registry/capability_registry.py - Capability contracts · Shared capability request/response contracts and naming.
deeptutor/capabilities/request_contracts.py - Agent workflows · Capability-specific pipelines for chat, solve, research, guide, question, and math animation.
deeptutor/agents - Core protocols · Capability, tool, context, stream, and trace primitives.
deeptutor/core/capability_protocol.py - LLM service · Model client, provider selection, routing, and telemetry.
deeptutor/services/llm/factory.py - RAG service · Parsing, chunking, embedding, indexing, and retrieval pipelines.
deeptutor/services/rag/service.py - State services · Session, memory, notebook, and workspace persistence.
deeptutor/services/session/unified_session_manager.py - Search service · Web and academic search provider adapters behind one interface.
deeptutor/services/search - Knowledge layer · Document ingestion and knowledge-base management shared by multiple capabilities.
deeptutor/knowledge/manager.py - Realtime bus · 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 · Terminal access to the same backend capabilities and storage.
deeptutor_cli/main.py - Web workspace · Browser workspace for chat, guide, co-writer, notebook, and utility pages.
web/app/(workspace) - Web client libs · 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 · Separate persistent agent platform for long-running bots and sessions.
deeptutor/services/tutorbot/manager.py - Bot loop · Autonomous loop, memory, skills, cron, heartbeat, and channel delivery.
deeptutor/tutorbot/agent/loop.py
Ops and config
Deployment packaging and runtime configuration.
- Deployment · Container and compose packaging for backend plus frontend.
docker-compose.yml - Config runtime · Shared settings, provider runtime, and environment loading.
deeptutor/config/settings.py
Connections 25
- 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.