ADR 0021: Frontend Compute Boundary

Status: accepted

Date: 2026-05-11

Context

UWScrape has a deliberately mathematical backend and solver model.

The backend owns academic statuses, source references, unknown propagation, conflict reporting, state persistence, and catalog-version anchoring.

The frontend must feel immediate enough for a 3D or atlas-style exploration experience.

That immediacy requires local computation.

The risk is that local computation could accidentally become a second academic authority.

The existing solver docs already require stable academic_result, explanation_tree, unknown_reason, conflict_reason, and source_reference payloads.

The existing graph view spec already defines bounded graph projections for frontend-heavy screens.

Decision

The backend computes academic truth.

The frontend computes interaction, rendering, temporary display state, visual filtering, and only bounded projection support needed for the currently visible slice.

The Rust/WASM worker computes deterministic layout and spatial kernels only for small active subgraphs, fallback cases, and interaction-local work that cannot reasonably wait on the network.

The frontend must not fork academic requirement evaluation.

The frontend must not decide whether a course unlock condition is academically satisfied.

The frontend must not decide whether a credential requirement is academically satisfied.

The frontend must not reinterpret unknowns or conflicts into stronger statuses.

The frontend must not derive source-backed course impact metrics that contradict backend metrics.

The frontend may compute camera state, hover state, selection state, picking, viewport state, semantic zoom, local visual filters, animation, label visibility, and small visible-subgraph preparation from already-loaded graph responses.

For dense catalog-wide graph work, ADR 0026 narrows this permission: server-side and index-build projection, closure, Advisory, and layout-hint precomputation are preferred, while browser layout is reserved for final rendering support, fallback, and small active subgraphs.

The frontend may show temporary local previews for unsaved user edits.

Temporary local previews must be marked as local or pending when they could be confused with backend academic results.

Consequences

Frontend performance work can proceed aggressively without weakening academic correctness.

Backend APIs must provide enough typed graph and query data that the frontend does not need to reverse-engineer requirement semantics.

The frontend can remain pleasant to use when panning, zooming, selecting, and expanding nodes.

The frontend must call the backend when a display claim becomes an academic claim.

The API client must preserve response statuses, warnings, unknowns, conflicts, and source references.

Visual geometry remains a projection.

Changing layout engines cannot change academic answers.

Alternatives Considered

Put every interaction in the backend

This would reduce browser complexity and weak-client CPU load.

It would make camera motion, hover, keyboard selection, and ordinary picking feel network-bound.

It would also force the backend to understand per-frame renderer concerns.

ADR 0026 accepts backend or index-build graph projection for dense catalog and Advisory work, but rejects making per-frame interaction network-dependent.

Let the browser solve academic requirements locally

This could make some interactions fast.

It would duplicate the most correctness-sensitive logic.

It would make source authority, unknown propagation, and future solver routing harder to audit.

Download the whole index and make the browser authoritative

This would reduce backend query load.

It conflicts with the accepted backend/index contract and state model.

It also makes publication, migration, and source-reference governance harder.

Verification

Frontend docs and code must draw a clear distinction between projection results and academic results.

Any UI status that means satisfied, not_satisfied, partial, unknown, conflict, or not_applicable must come from the backend result contract unless it is explicitly marked as a local preview.

The atlas worker contract must not include requirement-evaluation functions.