Spaces:
Sleeping
Sleeping
| # Architecture | |
| This document describes how Calculus Animator is wired together at runtime — the process model, IPC shape, module responsibilities, and lifecycle. It is the doc to read first when you want to understand or modify the system; the README focuses on what the app does for users. | |
| ## Process Model | |
| The running app spans **three Python processes** plus the embedded WebView, which together form a strict hub-and-spoke topology with the PyWebView shell as the user-facing root. | |
| ``` | |
| ┌──────────────────────────────────────────────────────────────────┐ | |
| │ Process A — PyWebView Shell (run.py → window.py) │ | |
| │ ┌──────────────────────────────────────────────────────────┐ │ | |
| │ │ Embedded WebView (browser engine, OS-native) │ │ | |
| │ │ Loads ui/index.html → ui/js/app.js + modules/* │ │ | |
| │ └──────────────────────────────────────────────────────────┘ │ | |
| │ │ | |
| │ Python side: api.bridge.CalculusAPI (exposed to JS as `pywebview.api`) │ | |
| │ │ │ │ | |
| │ │ └── HTTP ──► Process B (AI tutor backend) │ | |
| │ └── stdin/stdout JSON ────► Process C (slide render worker) │ | |
| └──────────────────────────────────────────────────────────────────┘ | |
| Process B — FastAPI AI Tutor Backend Process C — Pygame Render Worker | |
| (ai_tutor/main.py) (api/slide_render_worker.py) | |
| Bound to 127.0.0.1 Persistent subprocess | |
| HTTP/JSON Line-delimited JSON over stdin/stdout | |
| JSON access logs with request_id stderr drained to parent logger | |
| ``` | |
| - **Process A** owns the WebView and is the user-facing entrypoint. It instantiates `CalculusAPI` and registers it as the JavaScript-callable bridge. It also spawns and supervises Processes B and C. | |
| - **Process B** is a FastAPI server providing AI tutoring (RAG + LLM provider routing + vision). It is bound to loopback only and has no external network surface. | |
| - **Process C** is a long-lived pygame-based slide-render worker. The bridge talks to it via line-delimited JSON over stdin/stdout. There is at most one render worker; the bridge serializes calls with a render lock. | |
| Workers other than slide-render (e.g., capacity-test) are spawned on demand and torn down per call rather than kept persistent. | |
| ## IPC Shapes | |
| ### Bridge ↔ Render Worker | |
| - Transport: pipes (stdin write, stdout read, stderr read). | |
| - Encoding: one JSON object per line in both directions. | |
| - Reliability: stdout reads happen via a queue-fed reader thread with a configurable timeout (`CALC_ANIM_RENDER_TIMEOUT_SEC`, default 60s). On timeout the bridge kills the worker, restarts it on the next call, and returns a structured error to the caller. | |
| - Stderr: drained continuously by `_drain_stream_to_logger` daemon thread into the project logger at WARNING level with a `[render-worker]` label. Pipe buffer can never fill. | |
| - Crash detection: `_watchdog_loop` polls `proc.poll()` every `_WATCHDOG_INTERVAL_SEC` (default 2s); on crash it restarts the worker. Restart storms are bounded by `_MAX_CONSECUTIVE_RESTART_FAILURES` (default 3); once exhausted, subsequent calls return `capability_unavailable` instead of starting a restart loop. | |
| ### Bridge ↔ AI Tutor Backend | |
| - Transport: HTTP over loopback (`127.0.0.1:<port>`). | |
| - Encoding: JSON request/response. | |
| - Middleware order (outer → inner): `RequestIdMiddleware` → `AccessLogMiddleware` → `CORSMiddleware` → `MaxBodySizeMiddleware` → app. | |
| - Request IDs: `RequestIdMiddleware` honours an inbound `X-Request-Id` header (so the bridge can propagate its own correlation ID) or generates a UUID4 fresh. Always echoed in the response. The ID is bound to a `contextvars.ContextVar` so every `logger.*` call within the request automatically includes it. | |
| - Errors: all exceptions flow through three exception handlers (`HTTPException`, `RequestValidationError`, `Exception`) and emit a structured envelope: `{"error": {"type", "message", "request_id"[, "details"]}}`. No traceback or stack-trace text leaks into HTTP response bodies. | |
| - Outbound LLM calls: each provider call site validates the target URL against an allowlist before firing (SSRF protection). | |
| ### WebView ↔ Bridge | |
| - Transport: PyWebView's native JS-to-Python binding (no network). | |
| - API: methods on `CalculusAPI` are exposed under `pywebview.api.*` to the WebView JavaScript context. | |
| - Concurrency: JavaScript calls into the bridge can interleave; the bridge serializes worker stdin via `_render_worker_lock`. Per-call queue instances prevent reader-thread sentinels from leaking across worker generations. | |
| ## Module Responsibilities | |
| | Path | Responsibility | | |
| |------|----------------| | |
| | `run.py` | Canonical user-facing launcher. Drains backend `stderr` to the project logger, supervises the FastAPI subprocess, instantiates `CalculusAPI`, calls `webview.create_window`. Use `python run.py --help` / `--version` to inspect without launching. | | |
| | `window.py` | PyWebView shell helper. Importable; not a separate user-facing entrypoint. | | |
| | `scripts/build_release.py` | PyInstaller artifact builder. Release-only. Install build deps via `pip install -e .[build]`. | | |
| | `scripts/smoke_test.py` | Three-check non-interactive verification (backend constructs, bridge probe, end-to-end render pipeline). Exit 0 on pass. | | |
| | `api/bridge.py` | `CalculusAPI` — JS-callable methods, render-worker lifecycle, capacity probes. Owns the watchdog and stderr-drain machinery. | | |
| | `api/slide_render_worker.py` | Pygame-based persistent render worker. JSON-line protocol on stdin/stdout. | | |
| | `ai_tutor/main.py` | FastAPI app. Wires middleware, exception handlers, lifespan startup (calls `configure_logging()`), and route routers. | | |
| | `ai_tutor/middleware.py` | `RequestIdMiddleware`, `MaxBodySizeMiddleware`, `AccessLogMiddleware`. | | |
| | `ai_tutor/logging_config.py` | `request_id_var` ContextVar, `RequestIdFilter`, JSON formatter, `configure_logging()` (idempotent). | | |
| | `ai_tutor/providers/router.py` | Multi-provider LLM dispatch (DeepSeek, Google, OpenAI, Anthropic, Ollama). SSRF allowlist + per-provider URL validation. | | |
| | `ai_tutor/rag/` | Curriculum retrieval (ChromaDB-backed). Optional dependency; the package imports cleanly without `chromadb` installed. | | |
| | `core/` | Symbolic math: parser, detector, extractor, solver, step generator, animation engine. SymPy under the hood. | | |
| | `slide_renderer/` | Pygame slide rendering primitives (auxiliary package; not on the OSS POC critical path). | | |
| | `ui/index.html`, `ui/js/app.js` | WebView entrypoint and main JS module. | | |
| | `ui/js/modules/renderer.js` | Renderer module — math + slide rendering. Uses safe DOM APIs throughout; `katex` invoked with `trust: false`. Uses `_setSafe` / `_ensureChild` to prevent prototype-pollution writes. | | |
| | `ui/vendor/katex/`, `ui/vendor/mathlive/` | Vendored math libraries (KaTeX 0.16.11, MathLive 0.101.0) for offline rendering. | | |
| ## Lifecycle | |
| 1. User runs `python run.py`. | |
| 2. `run.py` checks/installs missing runtime deps, then spawns Process B (FastAPI backend) as a subprocess. Backend `stderr` is drained into the project logger via a daemon reader thread. | |
| 3. `run.py` instantiates `CalculusAPI` (which spawns Process C — the render worker — lazily on first call). | |
| 4. PyWebView opens the desktop window pointing at `ui/index.html`. | |
| 5. The frontend's `app.js` calls `pywebview.api.boot(...)` (or equivalent) to wire bridge ↔ UI. | |
| 6. User flows: solve / render / tutor calls flow through the bridge into the appropriate process. | |
| 7. Shutdown: ctrl+C or window-close terminates Process A; the bridge's watchdog terminates Process C; FastAPI's lifespan shutdown handler drains in-flight requests on Process B. | |
| ## Configuration Surface | |
| All runtime configuration is via environment variables (see `.env.example`): | |
| | Variable | Default | Purpose | | |
| |---|---|---| | |
| | `CALCANIM_MAX_REQUEST_BYTES` | 10485760 (10 MiB) | Maximum request body size accepted by the FastAPI backend. | | |
| | `CALC_ANIM_RENDER_TIMEOUT_SEC` | 60 | Render worker `readline` timeout. | | |
| | `_STARTUP_TIMEOUT_SEC` | 5 | Render worker startup timeout. | | |
| | `_WATCHDOG_INTERVAL_SEC` | 2 | Watchdog poll interval. | | |
| | `LLM_PROVIDER` | `deepseek` | Active LLM provider for the AI tutor. | | |
| | `DEEPSEEK_API_KEY`, `GOOGLE_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | — | Provider API keys (whichever provider is active). | | |
| ## Threading and Concurrency Model | |
| - **Process A** (PyWebView shell): main thread runs the WebView event loop. Daemon threads handle: (a) backend `stderr` drain, (b) render-worker `stderr` drain, (c) render-worker stdout queue feeder, (d) watchdog poll loop. | |
| - **Process B** (FastAPI): default uvicorn event loop. Per-request `contextvars.ContextVar` carries the request ID through async call chains. | |
| - **Process C** (render worker): single-threaded pygame loop, blocks on stdin between calls. | |
| Cross-process state is intentionally minimal — there is no shared memory or shared filesystem state beyond the read-only `data/` curriculum and the read-only `ui/` assets. | |
| ## Why This Shape | |
| - **PyWebView over Electron**: smaller distribution (~80MB vs ~200MB), single Python codebase, native OS integration without Chromium bundle. | |
| - **Subprocess workers over threads**: pygame can hang or crash; isolation protects the main process. Memory is isolated from the renderer's leaks. | |
| - **FastAPI bridge over direct PyWebView binding for AI tutor**: language-agnostic, future-proofing for web/mobile ports, async-native for concurrent solve+render+chat, OpenAPI documentation for free. | |
| - **Loopback-only over real auth**: this is a single-user desktop app. The host machine is trusted; the network boundary is the loopback interface. | |
| - **Vendored math libraries over CDN**: clients running offline (e.g., classrooms, restricted networks) need the app to work without network access. | |