ADR 0026: Server-Side Course Universe Projection Performance

Status: accepted

Date: 2026-05-13

Context

The course-first product model depends on a broad course universe, pathway closure, Advisory alternatives, and responsive Kanban editing.

Those workloads can become large enough that a student on an ordinary laptop should not be asked to compute them all in the browser.

Earlier frontend architecture decisions allowed Rust/WASM layout compute in a worker so the browser main thread stayed responsive. That remains useful for small active subgraphs, but it is not the desired long-term performance model for the full course universe.

The product should optimize for weak client hardware first. Browser GPU and WebGPU support are progressive rendering paths, not prerequisites for a good experience. The preferred long-term offload direction is toward index-build, backend cache, and eventually measured server-side accelerator paths, not toward requiring every browser to run the expensive graph algorithms.

Decision

UWScrape will prefer server-side and index-build precomputation for dense, catalog-wide, or solver-adjacent work.

The published index may include universal graph projection artifacts with deterministic layout hints.

The backend may cache derived course relation indexes, pathway traversals, closure traces, Advisory summaries, and graph projection slices by active index identity.

The browser owns final rendering, camera control, picking, hover, selection, small active-subgraph layout, and local draft responsiveness.

The browser should not be the primary compute target for:

full Faculty of Mathematics course-universe projection;
transitive prerequisite and unlock closure;
bounded Advisory alternative enumeration;
expensive pathway slicing;
large graph layout preparation.

Server-side GPU acceleration may be considered later for bounded graph projection, layout, or solver-preparation services when profiling proves CPU precompute and memory caches are insufficient.

Any server-side GPU path must still emit ordinary backend projection or solver contracts. It must not become a separate source of academic truth.

Server-side GPU work is an implementation accelerator behind the backend contract. It must not require a different frontend graph contract, different academic semantics, or browser GPU availability.

Consequences

Index build and backend runtime code must be able to produce and serve read-optimized projection artifacts.

Frontend performance tests should treat dense graphs as candidates for server/index-side projection or cached layout, even when Rust/WASM can handle the graph on a powerful developer machine.

Rust/WASM remains useful for small interactive graph slices and as a degraded fallback when precomputed layout hints are absent.

The universal Canva can load faster on weak laptops because expensive coordinate preparation can be performed before publication or inside backend caches.

Operational metrics should distinguish:

published_artifact;
runtime_cache_hit;
runtime_cache_fill;
client_layout;
server_layout_hint.

Relationship To Earlier ADRs

ADR 0021 remains authoritative for academic truth: the frontend must not compute academic meaning.

ADR 0023 remains authoritative for the first worker implementation, but its rejection of backend layout is narrowed. Backend or index-build layout is acceptable for dense catalog-wide projection artifacts; the rejected design is network-bound per-interaction layout for ordinary camera and selection work.

ADR 0022 remains authoritative for rendering: WebGPU is optional and cannot block core app use.

Rejected Alternatives

Make Browser WebGPU The Main Performance Strategy

Rejected because it would make the best product experience depend on client hardware and browser capability.

Push The Full Course Universe To The Browser And Let WASM Handle It

Rejected because it is hostile to ordinary student laptops and encourages browser-side recomputation of data that changes only when the published index changes.

Make Server-Side GPU Academic Truth

Rejected because academic truth must remain in the backend evaluator and solver contracts, with source references, unknowns, conflicts, and release-gated index inputs.

Require Server-Side GPU Before CPU/Cache Proof

Rejected for v1 because a careful CPU and cache path is simpler to verify and deploy locally. Server-side GPU becomes attractive only after profiling shows that precomputed projection artifacts, in-memory relation indexes, and bounded backend caches are not enough.

Verification

Dense graph preparation should recommend server projection or cached layout.

Published graph projection nodes should be able to carry deterministic layout hints.

The atlas worker should prefer valid backend/index layout hints over local coordinate generation.

Browser-side layout should remain available for small pathway, Kanban-relevant, and fallback graph slices.

Frontend performance reviews should flag any change that makes the full course universe depend on client-side closure, Advisory enumeration, or large layout recomputation.