Skip to content
uwwoe docs

Frontend

The frontend is a SvelteKit application under web/, written in TypeScript strict mode. It is delivered to the browser in two ways:

  • In production, the SvelteKit static build is embedded into the Go binary via the embed_frontend build tag, so uwwoe.fyi serves both the HTML/JS bundle and the API from one process.
  • In development, make dev-demo boots SvelteKit (default http://127.0.0.1:4173) and the backend (default http://127.0.0.1:18081) as separate processes, with SvelteKit proxying /api/v1 to the backend.

Routes (selected)

RoutePurpose
/Atlas canvas + Kanban side panel. The main interactive view.
/courses/<subject>/<catalog_number>Course detail + explanation tree. Renders without the atlas mounted.
/credentials/<credential_id>Credential requirements + progress against your Kanban.
/sources/<source_reference_id>Source citation detail.
/state/import, /state/export, /state/deleteAnonymous state lifecycle UI.
/timelineTerm-view planning board.

Transport validation

Every API response is validated through a Zod schema before the UI renders. This separates transport failures (the response shape did not match what the frontend expected — surfaces as EnvelopeIssues) from academic unknowns (the requirement could not be evaluated — surfaces as unknown status).

The two are deliberately distinct. A transport failure is a bug; an academic unknown is a feature. (Frontend-backend contract)

What the frontend does not do

The frontend is a projection only:

  • It never computes course_unlock, credential_progress, contribution, or feasibility locally — these come from /api/v1/query/* responses.
  • It never reinterprets statuses — satisfied | not_satisfied | partial | unknown | conflict | not_applicable render exactly as the backend returned them.
  • It never opens the index SQLite, never opens the state SQLite, never runs requirement evaluation, never stores raw tokens.
  • It never imports a fixed demo target array — course and credential search call backend endpoints.

These constraints are gates 3 and 6 in every phase’s success criteria, and they are encoded as ADR 0021. (Frontend compute boundary)

State token handling

The token is held in browser memory for the session and never:

  • Written to a query parameter.
  • Written to a URL fragment.
  • Sent to any third party.
  • Logged by the SvelteKit server in any access log.
  • Stored in localStorage by default (per ADR 0011).

The frontend can offer “remember on this device” with explicit user opt-in; the default is session-only.

Component anchors

  • ExplanationTree — renders an academic_result explanation tree with collapsible nodes and click-through to source references.
  • RequirementTree — credential requirement structure with per-rule status.
  • StatusBadge — renders one of the six states with consistent colour and screen-reader text.
  • SourceChipList — list of source-reference click-throughs.
  • EnvelopeIssues — distinct surface for transport validation failures.

Atlas integration

The atlas canvas is one component within the SvelteKit app. The non-canvas fallback — AtlasFallbackView — is a sibling component that renders the same view as a structured list when WebGL is unavailable. See Atlas renderer for the rendering details.

Want the full spec?