ADR 0022: Atlas Renderer WebGL and WebGPU Strategy
ADR 0022: Atlas Renderer WebGL and WebGPU Strategy
Status: accepted
Date: 2026-05-11
Context
The global exploration view is expected to render many courses, requirement groups, visual threads, overlays, labels, and interaction states.
The project wants a long-term path toward WebGPU without making early usability depend on WebGPU availability.
MDN documents WebGL as a web API for 2D and 3D graphics.
MDN documents WebGPU as powerful but subject to availability and secure-context requirements.
Three.js provides a mature WebGL renderer and also documents a WebGPU renderer.
Primary references:
Decision
The version 1 atlas renderer must support a Three.js WebGL baseline.
WebGPU may be added as a progressive renderer backend.
WebGPU absence must not block core application use.
Renderer choice must not affect academic results.
Renderer choice must not affect backend query semantics.
Renderer choice must not affect saved student state.
Renderer choice may affect frame rate, visual fidelity, batching strategy, label quality, and maximum comfortable visible-node count.
The frontend must expose a non-canvas 2D/list fallback for accessibility and low-power devices.
Consequences
The first frontend can target broad browser support through WebGL.
The renderer interface must hide the backend choice from higher-level atlas interaction logic.
The WebGPU backend can be introduced after the WebGL path proves the visual grammar and data flow.
Feature detection must be explicit.
Failure to initialize WebGPU must fall back to WebGL.
Failure to initialize WebGL must fall back to a non-canvas view.
The app should never show a blank core experience just because a graphics backend failed.
Alternatives Considered
Require WebGPU for v1
This would align with the long-term graphics direction.
It would make core app usability depend on a less universally available browser capability.
It is rejected for v1.
Use only DOM and SVG
This would simplify accessibility for small views.
It would likely struggle with a dense global atlas.
It remains appropriate for fallback views, detail views, and some explanation rendering.
Use Rust wgpu for browser rendering immediately
The Rust wgpu crate documents cross-platform graphics over native APIs and WebGPU/WebGL backends.
It is powerful, but it would increase early frontend integration complexity.
UWScrape will keep v1 rendering in TypeScript and Three.js while using Rust/WASM for layout compute.
Verification
The atlas implementation must have a renderer capability probe.
The WebGL path must be tested as the required baseline.
The WebGPU path must be tested only when available.
The fallback path must be tested without canvas support or when graphics initialization is disabled.