docs/ARCHITECTURE.md

# v5 architecture and boundaries

The hosted runtime adds a stateless text inference API and source-archive downloads to the oral trainer. The local runtime uses the same service, schemas, prompts and validators but routes language-model tasks either to a local CPU subprocess or to the remote Space through gradio_client.

Local identity is taken only from the authenticated Gradio request, never a client-supplied user ID. A ContextVar binds each backend call to that account. Each remote call constructs a token-bearing client for that account only and disposes of it afterwards; no global HF client is shared across users. Anonymous mode passes an explicit no-token value so the host's cached HF login is not used. There is no developer-token fallback.

Raw course originals are discarded after extraction. Saved courses contain a JSON manifest and NumPy embeddings without pickle; each belongs to an account ID. Loading rechecks ownership and embedding model identity. Browser working sessions remain separate from saved snapshots. Completed evaluations persist transcripts, rubric, checks, source IDs, topic and backend. Identical cached evaluations are inserted at most once per account/course/key.

The browser workflow evaluates only a server-stored transcription bound to the current rubric. The text-only inference API is separate: desktop clients must send transcript text because audio processing stays local. This is a study tool, not a proctored assessment system.

The local database uses SQLite, foreign keys and WAL. Passwords use salted PBKDF2-HMAC-SHA256 (600,000 iterations); tokens use Fernet and a key in a separate volume. Course/history data is not encrypted at rest. Use disk encryption and appropriate host permissions where required. Account deletion cascades to history and removes course snapshots; server restart clears lingering in-memory sessions after account changes.

Source citations and omission checks are retained from v4.3.2. Lexical citation alignment is a convenience, not proof of semantic entailment. Model errors remain possible; no academic-performance guarantees are made.

Remote inference requires explicit consent and a personal HF token unless anonymous mode was explicitly enabled by the installer. No silent switch to remote computation, no billed fallback, and no automatic retries that may unexpectedly repeat GPU usage are implemented. Requests time out with a warning that work may already have consumed quota.