Skip to content

ADR-0005: Viewer hosting — single-file static site, deployed via Pages

  • Status: accepted
  • Date: 2026-05-03

Context

The interactive viewer lets users compare formulations across views and cardinalities. Hosting candidates: GitHub Pages, Netlify, Vercel, self-hosted.

Decision

Single-file static site in viewer/index.html, deployed to GitHub Pages alongside the docs (under /viewer/). No build step. The viewer reads pre-baked JSON snapshots of every formulation's schema, hybrid, and ground views.

Rationale

  • Zero build pipeline for a v0.1 deliverable. A contributor can open viewer/index.html in a browser locally without npm, yarn, or a bundler.
  • GitHub Pages is the simplest path to a public URL given that the docs already deploy there.
  • The viewer's data is regenerated by a CI job (planned for v0.2); the user-facing site is static and cacheable.

Consequences

  • The viewer's logic is plain JS in a single HTML file. We accept the productivity ceiling this imposes (~few thousand lines) in exchange for zero-configuration deployment.
  • Larger interactivity (per-edge animations, formulation diffs) may warrant a build step in v1.x; revisit then.

Alternatives considered

  • React + Vite: heavyweight for v0.1.
  • D3 inside the docs site: would couple viewer hosting to mkdocs rebuilds; not desirable.