Skip to content
uwwoe docs

Frontend Application Shell Specification

Frontend Application Shell Specification

Status: draft

Last updated: 2026-05-11

Audience: frontend implementers, backend implementers, accessibility reviewers, and product-design reviewers.

Related documents:

Primary external references:

1. Purpose

This document defines the version 1 frontend application shell.

The shell is the user-facing frame around the atlas, detail pages, state editor, timeline, source inspector, and state lifecycle flows.

It specifies routes, layout regions, interaction states, accessibility requirements, and academic-result display rules.

It does not define backend API wire shapes.

It does not define the atlas layout algorithm.

It does not define course or credential evaluation semantics.

The backend owns academic meaning.

The frontend owns immediacy, projection, interaction, rendering, and user comprehension.

2. Framework

The frontend application must be built with SvelteKit and TypeScript.

The production frontend deployment must use the SvelteKit Node adapter/server unless a later ADR changes that decision.

SvelteKit route files should define page structure.

SvelteKit load functions may fetch page-level data when server or route loading improves user experience.

The app may use browser-side data fetching for highly interactive atlas operations.

The app must keep API behavior consistent regardless of whether a request originates from a route load function, component action, or browser-side client.

The app must use descriptive page titles because SvelteKit accessibility guidance uses titles for route announcements.

The app must preserve useful focus behavior during client-side navigation.

The app must not rely on SPA-only deployment as the primary v1 architecture.

3. Application Goals

The shell must let a student explore courses and credentials without first knowing the exact credential target.

The shell must let a student choose optional target credentials when they want a degree-CAD style workflow.

The shell must show unknowns and conflicts as normal states.

The shell must make source references reachable from any academic claim.

The shell must support mouse, trackpad, keyboard, and reduced-motion usage.

The shell must offer a non-canvas fallback for low-power devices and accessibility.

The shell must keep raw state_token values out of visible URLs.

The shell must never imply that a visual position, planet size, color, or thread is itself the academic source of truth.

4. Primary Routes

The initial route set should be small and stable.

Route names are product-facing and can evolve, but the route responsibilities are normative.

RouteResponsibility
/Atlas workspace and default exploration entry.
/courses/[subject]/[catalog_number]Course detail page for a canonical listing route.
/credentials/[credential_id]Credential detail page.
/stateStudent state editor.
/timelinePlanned and completed term timeline.
/sourcesSource/reference inspector entry.
/sources/[source_reference_id]Source/reference detail page.
/state/importState import flow.
/state/exportState export flow.
/state/deleteState deletion confirmation flow.

The course route must use subject and catalog number rather than a combined {course_code} route.

The payload must still preserve course_listing_id as the canonical machine identity.

The credential route must use the backend credential id.

The atlas route may open a course or credential in an in-page panel.

The dedicated course and credential routes must remain usable without the atlas canvas.

5. App Layout

The root layout must provide the global navigation frame.

The root layout must provide state-token awareness.

The root layout must provide catalog/version awareness.

The root layout must provide global warning surfaces.

The root layout must provide route-level error boundaries.

The atlas workspace must reserve the largest region for the atlas view.

The atlas workspace must provide compact side panels for current selection and filters.

The atlas workspace must provide a command surface for search, navigation, and state actions.

Panels must be resizable or collapsible where practical.

Panels must not cover essential warnings unless dismissed by the user.

The layout must adapt to narrow screens by replacing multi-panel desktop composition with stacked routes or sheets.

6. Visual Product Surfaces

The primary surfaces are:

  • atlas workspace;
  • course detail;
  • credential detail;
  • state editor;
  • timeline;
  • source/reference inspector;
  • import/export/delete state flows.

The atlas workspace is for exploration.

The course detail view is for exact inspection.

The credential detail view is for requirement understanding.

The state editor is for user-entered academic state.

The timeline is for term planning and progress context.

The source inspector is for provenance and trust.

State lifecycle flows are for preserving, exporting, importing, and deleting anonymous state.

7. Atlas Workspace Shell

The atlas workspace must mount the atlas engine only on routes where it is needed.

The atlas workspace must show a non-canvas fallback when atlas rendering is unavailable.

The atlas workspace must expose search.

The atlas workspace must expose target credential selection.

The atlas workspace must expose subject, level, status, and relevance filters.

The atlas workspace must expose selected item details.

The atlas workspace must expose current graph bounds and omitted counts when present.

The atlas workspace must expose active catalog metadata.

The atlas workspace must expose query warnings.

The atlas workspace must expose academic unknowns and conflicts without hiding the graph.

The atlas workspace must allow selection through keyboard navigation in fallback/list mode.

The atlas workspace must not require WebGPU.

8. Course Detail View

The course detail view must display:

  • subject;
  • catalog number;
  • title;
  • units display;
  • course listing id;
  • course credit identity when available;
  • cross-listing relationships when available;
  • prerequisites;
  • corequisites if present;
  • antirequisites if present;
  • enrollment constraints if present;
  • source references;
  • parser confidence or uncertainty indicators when relevant;
  • graph actions.

Graph actions should include:

  • show in atlas;
  • expand prerequisites;
  • expand unlocks;
  • run course unlock query;
  • run course impact query;
  • add completed course;
  • add planned course.

The view must distinguish course listing from course credit identity.

The view must not claim transfer credit, waiver, repeat, or contribution status unless the backend result supports the claim.

The view may show user notes separately from source-backed academic data.

9. Credential Detail View

The credential detail view must display:

  • credential name;
  • credential id;
  • credential type;
  • catalog version;
  • requirement groups;
  • requirement conditions;
  • status summary when student state is available;
  • gap summary when requested;
  • unknown requirements;
  • conflicts;
  • source references;
  • related courses;
  • graph actions.

The requirement display must preserve nested structure.

The requirement display must support all-of, any-of, choose-k, units-from, grade-threshold, average-threshold, level, progress, and opaque-text cases represented by backend responses.

The view must show opaque-text requirements as first-class unknown or manual-review items when the backend marks them that way.

The view must distinguish credential requirements from course prerequisites.

The view must distinguish desired credentials from declared credentials.

10. State Editor

The state editor must let the user manage:

  • completed courses;
  • grades;
  • planned courses;
  • academic progress;
  • academic standing;
  • declared credentials;
  • desired credentials;
  • unresolved course references;
  • unresolved credential references;
  • user notes;
  • UI preferences.

Academic progress and academic standing must be displayed as separate fields.

Completed and planned course inputs must preserve user-entered text when resolution is uncertain.

Grades must be optional.

Units must be displayed using backend-provided display text or exact machine units.

The state editor must not expose counts_for_credit as an authoritative user field.

The state editor may allow a user expectation note about contribution, but it must be visually separated from backend-computed contribution status.

The state editor must show catalog mismatch states when the backend reports them.

The state editor must support save, undo local edits, export, import, and delete flows.

11. Timeline View

The timeline view must display completed and planned courses by term.

The timeline view must support academic progress labels such as 1A, 1B, and 2A when present in state.

The timeline view must not infer academic standing from progress.

The timeline view may show term-level warning badges for unresolved courses, missing grades, unknown units, and catalog mismatch.

The timeline view may highlight prerequisites unlocked by a planned term only as a local preview unless backed by a what-if result.

The timeline view must make local preview status visible.

The timeline view must allow opening course detail from any course item.

The timeline view must allow opening relevant source references from academic result explanations.

12. Source Reference Inspector

The source inspector must display source references returned by backend responses.

It must prefer stable source links, source ids, hashes, and short snippets.

It must not broadly republish raw extracted calendar content.

It must show the official source as authoritative when the backend marks it so.

For Waterloo calendar data, the official source is the Waterloo Undergraduate Studies Academic Calendar or its linked official guidance.

It must distinguish source references from user-entered notes.

It must let a user navigate from an academic claim to the source reference.

It must let a user navigate from a source reference back to claims that used it when the backend provides that relationship.

The source inspector must handle missing or stale external links gracefully.

13. Command Palette

The app should include a command palette or equivalent keyboard-first command surface.

The command surface should support:

  • search course;
  • search credential;
  • go to atlas;
  • open state editor;
  • add completed course;
  • add planned course;
  • select target credential;
  • clear target credential;
  • export state;
  • import state;
  • delete state;
  • open source inspector.

Commands that mutate state must use the same backend state contract as visible forms.

Commands must not bypass confirmation for destructive flows.

Commands must not put the raw state_token in a command history visible to other users.

14. State Token Restore Flow

The app must accept raw state_token only through an intentional restore flow.

The app must not require email.

The app must not place the token in URLs.

The app must send the token to the backend using Authorization: Bearer <state_token>.

The app may keep the token in browser memory for the active session.

The app may offer an explicit local-device persistence option only if the risk is explained and the token is not logged.

The SvelteKit server must not store raw tokens.

The app must redact tokens from logs, telemetry, error messages, and screenshots produced by automated tests.

The app must treat invalid, deleted, expired, and unknown tokens with a similar user-facing recovery path unless the backend gives a safe distinction.

15. Import Flow

The import flow must accept a backend-supported state export document.

The import flow must validate the document before sending it to the backend when feasible.

The import flow must preserve user-entered unresolved text.

The import flow must display catalog-version information before applying the import.

The import flow must call backend import endpoints rather than modifying local state directly.

The import flow must surface migration preview warnings.

The import flow must distinguish transport errors from academic unknowns.

16. Export Flow

The export flow must call the backend export endpoint.

The export flow must be read-only from the frontend perspective.

The export flow must not cause a state mutation by itself.

The export flow must display catalog version and state schema version in the exported document summary.

The export flow must not show raw token verifier material.

The export flow may remind the user that the exported state document is sensitive if it contains grades and course history.

17. Delete Flow

The delete flow must require explicit confirmation.

The delete flow must call the backend delete endpoint.

After deletion, the app must clear in-memory token state.

After deletion, the app must clear local cached state data.

After deletion, a later token lookup should render like invalid-token recovery unless the backend specifies otherwise.

The flow must not promise server-side retention of deleted course history.

18. Target Credential Selection

The app must allow zero, one, or multiple desired credentials depending on backend state support.

The first UI may optimize for one active target credential while preserving desired credential arrays in state.

Target selection must be optional.

The app must support exploration without any target credential.

When a target credential is selected, the atlas may show relevance overlays from backend graph views.

When multiple targets are selected, overlays must distinguish combined relevance from per-target relevance if both are displayed.

The frontend must not compute credential contribution as academic truth.

19. Explanation Tree Rendering

The app must render explanation_tree payloads as structured explanations.

The rendering must support:

  • root status;
  • child conditions;
  • source references;
  • unknown reasons;
  • conflict reasons;
  • requirement group labels;
  • course references;
  • credential references;
  • numeric thresholds;
  • user-state facts.

The rendering must preserve backend status vocabulary.

The rendering must not collapse unknown into not_satisfied.

The rendering must not collapse conflict into not_satisfied.

The rendering must show partial progress separately from satisfied and not satisfied.

The rendering must allow users to expand details without requiring the atlas view.

20. Warnings, Unknowns, and Conflicts

Warnings must be visible near the result they affect.

Unknowns must be visible near the claim they weaken.

Conflicts must be visible near the state or requirement they affect.

Global warning banners may summarize high-risk issues.

Local detail panels must show exact issue context.

The UI must distinguish:

  • semantic academic unknown;
  • backend timeout;
  • backend unavailable;
  • invalid request;
  • catalog mismatch;
  • graphics fallback;
  • local preview.

The app must not use one generic error state for all of these.

21. Accessibility Requirements

The app must provide descriptive page titles.

The app must preserve keyboard access to primary workflows.

The app must provide focus management for panels and modal-like flows.

The app must provide a non-canvas fallback for atlas data.

The app must not make color the only indicator of status.

The app must support reduced-motion preferences for camera and animation behavior.

The app must expose text alternatives for visual status indicators.

The app must keep explanation trees usable with a screen reader.

The app must support source-reference inspection without canvas interaction.

The app must treat accessibility fallback as a core requirement, not a later nicety.

22. Keyboard Navigation

Keyboard navigation must cover:

  • global search or command surface;
  • route navigation;
  • atlas fallback lists;
  • panel open and close;
  • detail panel tabs;
  • explanation tree expand and collapse;
  • source reference activation;
  • state form editing;
  • state lifecycle confirmations.

The atlas canvas may support keyboard panning and zooming.

If canvas keyboard behavior is incomplete in v1, the fallback list must provide full access to graph nodes and actions.

Keyboard shortcuts must not be the only way to perform a destructive action.

23. Visual Status Vocabulary

The app must map backend academic statuses to stable visual treatments.

The app must keep those treatments consistent across atlas, detail, timeline, and explanation views.

The status vocabulary is:

  • satisfied;
  • not_satisfied;
  • partial;
  • unknown;
  • conflict;
  • not_applicable.

The app may add visual statuses for local UI conditions.

Local UI conditions must not reuse academic status labels unless they come from the backend.

Examples of local UI conditions include:

  • selected;
  • hovered;
  • loading;
  • stale;
  • pending_local_preview;
  • graphics_fallback;
  • omitted_by_bounds.

24. Loading States

The app must distinguish initial loading from background refresh.

The app must distinguish query cancellation from query failure.

The app must show stale data only when the user can understand that a refresh is pending.

The app must avoid blanking the atlas during small overlay refreshes.

The app must use skeletons or lightweight placeholders only when they clarify layout.

The app must not show fake academic data while waiting for backend responses.

25. Error Recovery

The app must provide recovery paths for:

  • backend unavailable;
  • invalid token;
  • catalog unavailable;
  • catalog mismatch;
  • unsupported index schema;
  • request too large;
  • graph bounds exceeded;
  • worker initialization failure;
  • WebGL initialization failure;
  • WebGPU initialization failure;
  • source link unavailable.

Recovery must be specific enough to guide the user.

Recovery must not reveal raw tokens.

Recovery must not suggest academic certainty when data is missing.

26. Local UI Preferences

The app may persist UI preferences through the backend state model when supported.

Preferences may include:

  • theme;
  • reduced motion override;
  • default atlas view mode;
  • panel widths;
  • preferred fallback mode;
  • last selected target credential;
  • visible subject filters.

Preferences must not affect academic results.

Preferences must not be required for evaluating a query.

Preferences must be safe to ignore during state migration.

27. Privacy

The app must treat course history, grades, desired credentials, and notes as sensitive.

The app must not send raw token values to third-party telemetry.

The app must not log request bodies containing student state in browser console output.

The app must not include raw tokens in route params or query strings.

The app must not include raw tokens in source reference links.

The app must avoid copying grades into nonessential diagnostics.

28. Observability

The frontend may emit local performance metrics.

Metrics must avoid raw tokens and full student course lists.

Useful metrics include:

  • route load duration;
  • API request duration;
  • atlas worker job duration;
  • frame time summary;
  • renderer backend selected;
  • fallback mode selected;
  • graph node count;
  • graph omitted count;
  • validation failure category.

Metrics must distinguish academic unknowns from system errors.

29. Testing Requirements

The app shell must be tested with unit tests for pure display logic.

The app shell must be tested with component tests for explanation tree rendering.

The app shell must be tested with integration tests for API client behavior.

The app shell must be tested with browser tests for core flows.

Playwright is the preferred browser test tool for later implementation because it is designed for end-to-end web testing.

Vitest is the preferred unit test runner unless later implementation research finds a concrete blocker.

Primary references:

30. Acceptance Scenarios

A user can open the app without a state token and explore the atlas.

A user can search for a course and open its detail page.

A user can select a target credential and see backend-provided relevance overlays.

A user can enter completed courses and grades, save state, and revisit using a token.

A user can inspect why a course is locked, partially unlocked, unknown, or conflicting.

A user can inspect source references for a credential requirement.

A user can export state without causing a state mutation.

A user can delete state and lose access through the old token.

A user can use the app when WebGPU is unavailable.

A user can use a non-canvas fallback when the atlas cannot initialize.

31. Non-Goals

The shell does not implement a full degree-planning solver.

The shell does not choose official academic advice.

The shell does not replace Waterloo advising.

The shell does not scrape live calendar data.

The shell does not store raw token verifier material.

The shell does not make WebGPU mandatory.

The shell does not make the atlas canvas the only route to information.

32. Implementation Notes

Use operational component names.

Avoid naming core components after visual metaphors.

Use names such as AtlasWorkspace, CourseDetail, CredentialDetail, StateEditor, TimelineView, SourceInspector, ExplanationTree, and StateTokenRestore.

Visual copy may use planet, island, thread, or atlas language when it helps users understand the experience.

Internal contracts should prefer academic and operational names.

33. Review Checklist

Every academic claim must trace to a backend payload.

Every unknown must remain visible.

Every conflict must remain visible.

Every source reference must be reachable.

Every destructive state flow must require confirmation.

Every route must have a meaningful non-canvas path.

Every token flow must avoid URLs.

Every primary workflow must be keyboard reachable.

Every frontend cache must respect backend catalog/version metadata.