ADR-004 — Hash-based client-side routing

Status · Superseded by ADR-013 (History API via SvelteKit router) Date · 2026-04-01 · Superseded April 2026 TA anchor · §stack · §components/router

Context

Six screens need to be navigable by URL. The application is served as static files by nginx. Deep-linking must work without server-side redirect logic.

Decision

Hash-based routing. Routes are #/screen with optional query params (#/fly?mission=curiosity). The router reads window.location.hash and hashchange events.

Rationale

Hash routing works without server-side configuration — nginx serves index.html and the browser handles the hash fragment client-side. History API routing requires either a server-side catch-all redirect or a build step that generates per-route HTML files. Hash routing is simpler and more robust for a static deployment.

Alternatives considered

• History API routing — cleaner URLs; requires server-side redirect config or build-time static generation. Adds server config complexity for no user-facing benefit in v1.
• No routing (direct HTML files per screen) — prototypes work this way; not viable for production where state must be shared between screens and URLs must be bookmarkable.

Consequences

Positive: works with any static file server; no nginx configuration needed for routing. Negative: URLs contain #; slightly less clean aesthetically. History API routing is a v2 candidate (RFC-001).