Architecture diagrams

after phases 1–4

A visual reading of the approved decisions. Solid shapes are in scope for the MVP. Teal marks every place an LLM, embedding or speech model is called. Dashed shapes are agreed but deferred.

Decisions this picture is built on

Phase 1 · LMS core

·Organization-first tenancy; a solo teacher is an org of one
·Global student identity, org membership by invite, CSV, later SSO
·Per-course progression rules, certificates with optional expiry
·Roles: super-admin, org admin, educator, student

Phase 2 · Builder & testing

·Block editor with AI co-pilot panel; AI output is always editable blocks
·Auto-graded core set, LLM-graded open answers, 3D practical scoring
·Grounded in uploads by default, per-request toggle
·Widget and Scene DSL first-class; sandboxed iframe embeds second-class

Phase 3 · 3D / VR

·Three.js via React Three Fiber, JSON Scene DSL, no generated code
·2D screens first; WebXR on Quest enabled and smoke-tested
·Guided interaction, light physics
·Subject-agnostic asset search behind an automated quality gate
·QA: play-test, inspector, chat edits, versions, pilot cohort

Phase 4 · RAG & tutor

·Text chat with citations at MVP; voice and 3D avatar later
·Direct or Socratic per course; exam lockdown
·Unknowns: say so, labeled general answer, escalate, pin to FAQ
·Multilingual from day one
·Cloud APIs by default, self-hosted models for some tenants

1. System layers

Every client talks to one edge that resolves the tenant and sets the database session. Services below it never see a request without a tenant. AI calls from any service go through one router, which is what makes per-tenant self-hosting possible later without touching the services.

All six services read and write Postgres under row-level security; only the arrows that carry the argument are drawn. Ingestion, Tutor, Generation and Asset Search are the four services that spend tokens, and all four reach models only through the router.

MVP componentcalls an AI modelagreed, deferred

2. Material ingestion and the tutor loop

Index time runs once per upload and is cheap. Query time runs per student question and is where the recurring cost lives, so the FAQ cache sits in front of retrieval and the course digest stays in the cached prompt prefix.

Hybrid search reads the pgvector and full-text indexes built above. A cache hit skips retrieval and the model entirely. Every pinned educator answer becomes a future hit, so the course gets cheaper and more accurate as it is used.

3. Vibe-coding pipeline and the asset quality gate

The model never writes engine code. It writes a validated JSON document, and every later edit is a patch to that document. The same pipeline produces quizzes, 2D widgets and 3D scenes, only the schema changes.

Every approved asset is cached in normalized form, so the catalog grows into a curated library without anyone curating it. The Compiler only ever sees asset IDs and a bounding box, never geometry.

4. Content and learning records

One shared primitive: a Block is a JSON document whatever its kind. Versions are immutable once published, attempts are append-only, and both decisions are what let audit-grade reporting be added later without a migration.

Attempt records the pinned BlockVersion it was taken against, so a scene or quiz can be edited for the next cohort without rewriting anyone's history. The dashed billing entities are modeled in Phase 5 and ship without a payment gateway.

5. Which model does what

Routing by task is the main cost control. The router applies the same table per tenant, swapping the cloud column for the self-hosted one where a tenant's policy requires it.

Task	Cloud default	Self-hosted equivalent	Per-unit estimate	Lever
Chunk context lines, query rewrite, grading rubric checks	claude-haiku-5-5	small open-weight via vLLM	cents per course	Batch API, prompt caching
Tutor answers	claude-sonnet-5-5	mid open-weight via vLLM	≈ $0.01 / question	cached digest, FAQ cache, top-k ≤ 6
Scene, widget and quiz compilation	claude-opus-5-5	large open-weight via vLLM	≈ $0.10 full, $0.02 patch	JSON DSL, cached schema docs, patches
Embeddings	BGE-M3 (hosted or API)	BGE-M3	cents per course	same model both sides, no re-index
Transcription	WhisperX (hosted)	WhisperX	≈ $0 self-hosted, $0.006 / min API	run once, store timestamps
Rerank	bge-reranker-v2-m3	bge-reranker-v2-m3	negligible	CPU-capable
Asset fit scoring	claude-haiku-5-5 (vision)	open VLM	cents per search	cache scores per asset

Estimates use Anthropic list prices as of October 2026 and are order-of-magnitude. student questions dominate recurring spend