DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Architecture and source owners
Handbook · Development · Events
DeepTutor 1.7.0 is one source repository with independently packaged Python modules. CLI, WebSocket and Python SDK entry points converge on a durable application service before executing a capability.
flowchart TD
CLI[Typer CLI] --> APP[TurnApplicationService]
WS[WebSocket adapter] --> APP
SDK[DeepTutorApp SDK] --> APP
APP <--> STORE[Session store and runtime coordinator]
APP --> ENGINE[TurnEngine]
ENGINE --> ORCH[ChatOrchestrator]
ORCH --> CAP[Selected capability]
CAP --> LOOP[Agent loop or stage pipeline]
LOOP --> TOOLS[Authorized tool registry]
CAP --> BUS[Per-turn StreamBus]
BUS --> STORE
STORE --> REPLAY[Adapter replay to consumers]
Trace a request
| Responsibility | Source owner |
|---|---|
| CLI parsing and commands | deeptutor_cli/main.py |
| SDK facade and application requests | deeptutor/app/ |
| Durable admission, execution and replay | app/service.py |
| WebSocket adaptation | unified_ws.py |
| Lower-level execution | runtime/turn_engine.py |
| Context-to-capability routing | runtime/orchestrator.py |
| Capability/tool registration | runtime/registry/ |
| Module-owned contributions | modules/manifests/ |
| Shared chat loop | agents/loop/ |
| Persistent sessions and turn lifecycle | services/session/ |
| Worker leases and notifications | runtime/coordination/ |
UnifiedContext in core/context.py is the
execution context. Entry points should use the application service rather
than instantiate an orchestrator to bypass durable state. Persistence,
submission identity, replay, cancellation and recovery belong to the shared
application/runtime path. See events before changing
stream behavior.
Tools, capabilities and modules
A tool is one model-selected operation. A capability owns a complete turn and
may run a shared loop or a multi-stage pipeline. chat is the default;
capability activation and context determine additional tool availability.
Every capability emits the common result envelope, including usage costs.
See extension contracts.
Official module manifests own package paths, dependencies, capabilities, routers, CLI groups, navigation and lifecycle callbacks. Installed, enabled and ready are separate states. Metadata must be readable without importing unavailable feature packages. Third-party plugins add review and lifecycle rules of their own; they are not the same as official module wheels.
Configuration and isolation
runtime/home.py resolves the runtime home;
services/config/runtime_settings.py
owns settings and supported process overrides. Runtime settings live under
data/user/settings/; .env is not an application configuration source.
Container startup has its own JSON-to-environment handling, described in
Containerization.
Account authorization and workspace selection are separate checks. Paths and
services resolve through services/workspace/
and services/path_service.py.
Selected workspace data, account credentials and shared resource grants have
different lifetimes; consult storage and
workspace contracts before touching migrations or caches.
Frontend boundaries
The Next.js App Router in web/app/ composes pages. Domain,
store and transport slices live under web/features/.
Reusable UI and transport primitives live under web/shared/.
web/contracts/ holds generated API and turn contracts.
The dependency rules prohibit cycles,
imports of route page.tsx modules, upward dependencies from shared code,
and rendering-layer imports from feature domain/store/transport code except
for the named settings-store exception. Prefer existing transport and store
owners to component-local WebSocket, retry or persistence implementations.
web/proxy.ts forwards API/WebSocket traffic to the
backend. Browser settings and runtime server configuration are different
boundaries; do not bake deployment addresses or secrets into client code.
Experimental engine path
The Python scheduler remains the default. DEEPTUTOR_CHAT_ENGINE can select
experimental TypeScript paths implemented in
packages/chat-engine/ and
runtime/ts_engine/. The native path has
compatibility checks and Python integration points. An old migration plan is
not evidence that the whole backend has moved to TypeScript. Changes here
must preserve the application service, storage and public event contracts;
see the dedicated engine jobs in Testing.