> ## Documentation Index > Fetch the complete documentation index at: https://docs.suchi.page/llms.txt > Use this file to discover all available pages before exploring further. # SPA architecture > Onboarding doc for anyone touching ui/ — layout, build, routing, state, design system, and the guard-rails that keep the frontend small. Read this before adding a feature to `ui/`. It takes \~20 minutes and after it you should be able to add a route, wire an endpoint, and ship without breaking the things that are deliberate. Companion to [SPA backend](/spa-backend), which documents the server side of the contract. ## 1. What this frontend is, in one paragraph A single-page Svelte 5 app, compiled by Vite into **three static files** (one HTML, one JS, one CSS), committed into the Go repo and embedded into the suchi binary with `go:embed`, served at `/app/`. It has **zero runtime npm dependencies** — no component library, no router package, no icon package, no CSS framework, no webfonts. Everything it knows about the world arrives through suchi's documented HTTP API, the same one the mobile apps and agents use. Current weight: \~50 KB gzipped JS + \~4.5 KB CSS. That number is a feature; treat it like a budget, not a coincidence. ## 2. The constraints that explain everything else Every architectural choice below falls out of four constraints. When you're unsure how to build something, re-derive from these: 1. **suchi is one binary.** The UI must not add a runtime, a sidecar, or a deployment step. Hence: static build, embedded, no SSR, no SvelteKit (its server layer would be dead weight — the Go binary *is* the server). 2. **Contributors build the Go project without Node.** Hence: the built `dist/` is committed to `core/ui/spa/dist/` (marked linguist-generated). Node/bun is only needed when you touch `ui/`. 3. **The API is the only door.** No private endpoints for the UI. If the UI can do something, an agent token can do the same thing with the same calls. This keeps the UI honest and the API complete — several server endpoints (`/api/stats/`, `/api/events/`, `/api/jd/categories/`) exist because the UI needed them and the need generalized. 4. **Minimal supply chain, by org policy.** Three devDependencies (`svelte`, `vite`, `@sveltejs/vite-plugin-svelte`), pinned via lockfile, no postinstall scripts. Adding a dependency is a design review, not an `npm install`. ## 3. Repo layout & the build pipeline ``` ui/ index.html entry; favicon data-URI, manifest link, theme-color vite.config.js base:'./', dev proxy → :8000, single-chunk output public/manifest.webmanifest src/ main.js mount(App) app.css THE design system — all global styles live here App.svelte shell: sidebar, topbar, drawer, routing outlet lib/ api.js every HTTP call in the app; nothing fetches elsewhere session.svelte.js auth state + theme ($state rune module) router.svelte.js ~20-line hash router format.js dates, bytes, sensitivity→dot-color Icon.svelte hand-drawn 24×24 stroke icons (a path table) Palette.svelte ⌘K command palette routes/ one file per page: Dashboard, Documents, DocumentDetail, Search, Tasks, Automations, Upload, Settings, Setup, Trash, Login core/ui/spa/ spa.go go:embed + /app/ handler (SPA fallback to index.html) dist/ committed build output — NEVER edit by hand ``` The pipeline, and the rule that protects it: ``` edit ui/src → cd ui && bun run dev (Vite on :5173, proxying to a running `suchi serve` on :8000) → `make ui` (bun-first, npm-fallback; runs vite build and copies into core/ui/spa/dist) → `make build` (go:embed bakes AT COMPILE TIME) → restart binary → hard-refresh /app ``` **The classic failure** (it has happened): committing a new `dist/` without rebuilding the binary, or editing `ui/src` without running `make ui`. Source, dist, and binary are three snapshots that only agree if you run the pipeline. The CI stale-dist check (paths-gated on `ui/**`, builds and diffs against the committed dist) exists to catch exactly this — keep it green. **Sync discipline:** the `ui/` tree is replaced wholesale or patched with a reviewed diff. Never hand-port features between trees by eye — that's how the repo once ended up with a source tree older than its own committed dist. ## 4. Routing Hash routing (`#/documents`, `#/doc/42`, `#/search?q=tax`), implemented in `router.svelte.js`: parse `location.hash` into `{path, parts, query}` held in a `$state` object, updated on `hashchange`. That's the whole router. Why hash and not history-API paths: the SPA is served at `/app/` behind arbitrary reverse proxies. Hash routes need **zero server route configuration** — no catch-all, no rewrite rules — and deep links survive any hosting arrangement, including `file://` during a quick check. The Go handler only has to serve `index.html` for `/app/` and the two asset files. Adding a route: create `src/routes/Thing.svelte`, import it in `App.svelte`, add a branch to the `{#if page === …}` chain and (if nav-worthy) an entry in the `nav` array. There is no route registry beyond that chain — with \~11 routes, a registry would be architecture cosplay. ## 5. State: Svelte 5 runes, and what we deliberately don't have The app uses runes (`$state`, `$derived`, `$effect`, `$props`) throughout — no legacy stores, no `$:` labels. Cross-cutting state lives in `.svelte.js` modules exporting `$state` objects (`session.svelte.js` is the pattern). Everything else is **component-local**: each route owns its data, fetches on mount, and refetches on its own triggers. There is deliberately **no global cache/store layer** (no Redux-alike, no query library). Routes remount on navigation and refetch; the API is local and fast, and the payloads are small. The two pieces of genuinely shared server state — the stats snapshot and the events feed — live in `App.svelte` and flow *down* as props (see `Dashboard`). If you're about to build a cache, first check whether a 60-second poll and a refetch-on-visibility (`Documents` does this) already solve it, because so far they always have. Persistence uses `localStorage` under a `suchi.` prefix, always wrapped in try/catch (private-mode Safari throws): `suchi.token`, `suchi.theme`, `suchi.jd.open` (sidebar tree), `suchi.events.seen` (activity read cursor), `suchi.setup.dismissed`, `suchi.docs.view` (list/grid). Nothing sensitive beyond the API token goes in storage, and the token is same-trust-level as the cookie. ## 6. The API layer — one file, several load-bearing conventions `lib/api.js` is the only place `fetch` appears. Conventions: * **Named function per endpoint**, thin, with the wire contract in a comment where it isn't obvious. Grep-ability beats abstraction. * **Auth**: every request sends `Authorization: Token …` if a token is stored, plus `credentials: 'same-origin'` so the session cookie rides along. JSON login returns a token *and* sets the cookie (server-side decision); the token covers API calls, the cookie covers things that can't carry headers — `