# 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.