ADR 0020: SvelteKit Frontend Application Framework

Status: accepted

Date: 2026-05-11

Context

UWScrape needs a browser interface that can support ordinary pages, detail panels, state editing, source-reference inspection, and a large interactive atlas view.

The backend architecture already assigns academic evaluation, source-backed query semantics, solver routing, state persistence, and index authority to the Go backend.

The frontend must be expressive enough for complex interaction while remaining strict about not becoming an academic truth engine.

The user has prior positive experience with Svelte and prefers a frontend stack that feels less ceremonial than heavier component frameworks.

Svelte documents itself as a compiler-based UI framework, and SvelteKit documents file-based routing, load functions, server hooks, accessibility behavior, performance features, and adapter-based deployment.

Primary references:

Decision

UWScrape will use SvelteKit with TypeScript as the frontend application framework.

The version 1 production frontend deployment will use the SvelteKit Node adapter/server.

The SvelteKit server is a frontend runtime.

It may own page rendering, route loading, frontend asset delivery, same-origin API proxying, frontend request metadata, and frontend observability.

It must not read the published SQLite index directly.

It must not run academic evaluation.

It must not route solver requests except by calling the Go backend API.

It must not mutate student state outside the Go backend API.

It must not store raw state_token values server-side.

The Go backend remains the academic/API authority.

Earlier language saying the Go backend may serve static frontend assets remains valid only as an optional local or fallback deployment mode.

It is not the primary v1 frontend deployment path after this ADR.

Consequences

Frontend source will likely live under web/.

Frontend implementation should use TypeScript strict mode unless a concrete implementation blocker is discovered.

SvelteKit route and load semantics should shape the application shell.

The frontend can choose between SvelteKit load functions and a client server-state library for browser-side interactive data, but the API contract must remain the same.

Node server deployment gives long-term room for route rendering, safe proxying, headers, observability, and future session work.

The added server process increases operational complexity compared with serving static assets from the Go process.

That complexity is accepted because the frontend is expected to become an application surface, not a small static dashboard.

The SvelteKit server must stay thin enough that disabling it for a local static fallback would not change academic semantics.

Alternatives Considered

Static assets from the Go process as the primary v1 path

This would produce a simpler runtime topology.

It would also push more browser routing and deployment compromises into the frontend.

It remains acceptable as a fallback mode, but it is not the primary v1 direction.

Other mainstream JavaScript application frameworks

Other mainstream frameworks are mature options with broad ecosystems.

The project does not currently need framework-specific capabilities that would outweigh the user’s Svelte preference.

SvelteKit better matches the user’s preference for a compact mental model.

Static SvelteKit adapter as the primary v1 path

This would reduce server operations.

It would also remove useful room for server-side loading, same-origin proxying, and frontend observability.

The static shape can remain a fallback or later deployment option, but it is not the v1 default.

Verification

Future implementation should prove this ADR by creating a SvelteKit TypeScript app, using the Node adapter for production builds, and keeping all academic API calls routed through the Go backend contract.

Docs that describe static asset serving must call it optional or fallback.

Docs must not imply that the SvelteKit server is an academic backend.