Skip to content
uwwoe docs

Architecture overview

uwwoe is a five-stage system. This page is the 10,000-foot view; each stage has its own page underneath.

The flow

         ┌────────────────────────────────────┐
         │  Waterloo Kuali catalog (public)   │
         └─────────────────┬──────────────────┘
                           │  offline, manual cadence
                           ▼
        ┌────────────────────────────────────────┐
        │  Offline scraper + parser + validator   │
        │  cmd/uwscrape  (Go CLI)                 │
        └─────────────────┬──────────────────────┘
                          │  release-gated build
                          ▼
        ┌────────────────────────────────────────┐
        │  Published index artifact (read-only)  │
        │  course-universe.sqlite                │
        │  build-metadata.json                   │
        │  validation-summary.json               │
        │  release-decision.json                 │
        │  build-report.md                       │
        └─────────────────┬──────────────────────┘
                          │  loaded at startup, never re-fetched
                          ▼
        ┌────────────────────────────────────────┐
        │  Go HTTP backend                       │
        │  cmd/uwscrape-server                   │
        │   • read-only index access             │
        │   • writable state SQLite (separate)   │
        │   • /api/v1 envelope responses         │
        │   • direct evaluator (academic truth)  │
        └─────────────────┬──────────────────────┘
                          │  same-origin, /api/v1
                          ▼
        ┌────────────────────────────────────────┐
        │  SvelteKit frontend                    │
        │  web/                                  │
        │   • Kanban, Canva, Advisory widget     │
        │   • Zod transport validation           │
        │   • renders backend statuses verbatim  │
        └─────────────────┬──────────────────────┘
                          │  small subgraph layout jobs
                          ▼
        ┌────────────────────────────────────────┐
        │  Rust/WASM atlas layout worker         │
        │  crates/atlas-layout-wasm              │
        │   • RustWasmLayoutWorker               │
        │   • no academic evaluation             │
        └────────────────────────────────────────┘

Core principles

These are not aspirations; they are enforced by per-phase global gates and locked ADRs.

  1. Backend owns academic truth. Frontend never computes whether a course is unlocked, whether a credential is complete, or whether a conflict exists. (ADR 0021)
  2. No runtime scraping. The backend never contacts Waterloo or Kuali at request time. Index publication is a deployment operation. (ADR 0001, ADR 0010)
  3. Source references survive end-to-end. Every claim is traceable from the rendered explanation node back to the Kuali excerpt that defined it.
  4. Anonymous-only. No account, no email, no student number; tokens only via Authorization header; hard delete on request. (ADR 0011, ADR 0019)
  5. Fail closed. Unsupported index schemas, missing release decisions, rejected release decisions — all refuse to serve traffic. (ADR 0007, ADR 0010)
  6. Conservative engines. Engine UNKNOWN, timeout, or UNSAT never become academic statuses by themselves; they are always mapped through a documented unknown/conflict reason. (ADR 0018)

Stack summary

LayerStackSpec
Offline pipelineGo CLI (cmd/uwscrape) → SQLite artifactScraper pipeline
Backend runtimeGo HTTP service (cmd/uwscrape-server), fail-closed startup, /api/v1 envelopes, direct-evaluator academic engineBackend API, Backend runtime operations
State storeSeparate SQLite, anonymous bearer tokens, HMAC verifier server-sideBackend state storage, Student state schema
FrontendSvelteKit + TypeScript strict, Node adapter, Zod transport validationFrontend application shell, Frontend-backend contract
Atlas rendererThree.js (WebGL baseline) + Rust/WASM layout worker + non-canvas fallbackAtlas engine and WASM

Where to go next