biggus-dickus/docs/superpowers/specs/2026-06-03-frontend-spa-milestone-1-design.md

Frontend SPA — Milestone 1 (Foundation Slice) — Design

Date: 2026-06-03 Status: Approved (brainstorming) — ready for implementation planning.

Context

The backend MVP is code-complete: an authenticated admin HTTP API (object CRUD + flexible fields, vocabulary/authority/term management, stepwise publishing, search, audit), a public read API, and a code-first OpenAPI document (utoipa). There is no frontend yet. VISION + docs/specs/2026-06-02-mvp-architecture.md §17 call for a lean React SPA in web/ that consumes the OpenAPI, with sv/en localization and an explicit "potato hardware" bundle-discipline budget.

The admin UI is a large surface, so it is decomposed into milestones, each with its own spec → plan → implementation cycle:

1. Foundation slice (this spec): scaffold, build/dev/serve, typed API client, app shell (nav + i18n), login/session, and the Objects screen (paginated list + read-only detail).
2. Object authoring — create/edit/delete + the dynamic flexible-field form driven by field-definitions.
3. Publishing workflow — stepwise draft→internal→public UI with the required-field gate.
4. Vocabulary & authority management.
5. Search UI.

Goal (Milestone 1)

A walking skeleton that proves the whole pipeline end-to-end — log in → fetch → render → embedded in the binary — and lands a real, usable screen (browse + read catalogue objects). Every piece of plumbing here is reused by later milestones.

Decisions (settled during brainstorming)

• Stack: React + TypeScript + Vite, pnpm, shadcn/ui components, TanStack Query for server state, react-i18next for sv/en.
• API client (Option A): openapi-typescript generates types from the OpenAPI JSON; openapi-fetch (tiny typed wrapper) for calls; TanStack Query hooks written by hand. Smallest dependency surface, contract auto-synced, query layer under our control.
• Layout (Option C): two-pane master–detail — object list on the left, the selected record fills the right pane (inspector style; efficient for browse + later edit-in-place).
• Testing (Option A): Vitest + React Testing Library + MSW (Mock Service Worker) — component/hook tests in-process; MSW intercepts fetches with handlers typed against the generated schema, so tests stay honest to the OpenAPI contract without a browser. A Playwright e2e smoke is deferred to a later milestone (fits once --seed data exists).
• Bundle budget: initial JS ≤ 150 KB gzipped, tracked in CI.

Scope (YAGNI)

In:

• web/ scaffold + build/dev/serve (incl. release embedding).
• Generated typed API client + TanStack Query hooks.
• App shell: compact icon sidebar (Objects active; later items shown disabled / "coming soon"), top bar with sv/en switch + user menu (logout).
• Auth: login page, logout, session guard.
• Objects two-pane: paginated list (left) + read-only detail (right) showing the inventory-minimum fields and flexible-field values, with a visibility badge.

Out (later milestones): create/edit/delete and dynamic field forms (M2), publish workflow (M3), vocabulary/authority/term management (M4), search UI (M5), media/ thumbnails. Later nav items appear as disabled stubs so the shell's shape is visible.

Architecture

Project layout (web/)

web/
  package.json              pnpm; scripts: dev, build, test, typecheck, lint, gen:api
  vite.config.ts            dev proxy /api,/api-docs,/health -> http://localhost:8080
  tsconfig.json
  index.html
  components.json           shadcn/ui
  src/
    main.tsx                entry: QueryClientProvider, i18n, router
    app.tsx                 route table
    api/
      schema.d.ts           generated (openapi-typescript) — committed
      client.ts             openapi-fetch client; credentials:'include'; 401 middleware
      queries.ts            useMe, useObjectsPage, useObject, useLogin, useLogout
    auth/
      session.tsx           session context (via /api/admin/me); RequireAuth guard
      login-page.tsx
    shell/
      app-shell.tsx         icon sidebar + top bar + <Outlet/>
      lang-switch.tsx
    objects/
      objects-page.tsx      two-pane container (list + detail by :id)
      object-list.tsx
      object-detail.tsx
      visibility-badge.tsx
    i18n/
      index.ts              react-i18next init
      en.json  sv.json
    components/ui/...        shadcn primitives
    test/
      setup.ts              Vitest + RTL + MSW server
      handlers.ts           MSW handlers typed against schema.d.ts

Serve / build model

• Dev: pnpm dev runs Vite on :5173, proxying /api, /api-docs, /health to the Rust server on :8080 (run separately). Session cookies stay same-origin through the proxy. Backend dev/test loop is unchanged and independent of the frontend.
• Release: pnpm build → web/dist, embedded into the server binary via the memory-serve crate and served at / with an SPA fallback (any non-/api, non-/health, non-/api-docs path → index.html for client-side routing).
• Feature gate embed-web (off by default) on the server crate guards the memory-serve embedding, so cargo build/cargo test never require a built web/dist. CI builds the SPA first, then cargo build -p server --features embed-web for the release artifact. Milestone 1 proves this embed path end-to-end.

Data flow

1. App mounts → useMe() queries /api/admin/me. 200 → session established; 401 → the client middleware redirects to /login.
2. /objects → useObjectsPage(limit, offset) → GET /api/admin/objects (the paginated admin list already built). Left pane renders rows; selecting one routes to /objects/:id.
3. /objects/:id → useObject(id) → GET /api/admin/objects/{id}. Right pane renders inventory-minimum fields + flexible-field values + visibility badge; 404 → not-found state.
4. Login: useLogin → POST /api/admin/login (session cookie set); on success invalidate useMe and navigate to /objects. Logout: POST /api/admin/logout → clear → /login.

Routing

Path	Access	Renders
/login	public	login page (redirects to /objects if already authed)
/	protected	redirect → /objects
/objects	protected	two-pane; empty right pane prompt
/objects/:id	protected	two-pane; right pane = record
*	protected	redirect → /objects

RequireAuth wraps protected routes; unauthenticated → /login.

Error / loading / empty states

• List: loading skeleton; empty ("no objects yet"); error with retry.
• Detail: loading; 404 not-found; error with retry.
• Login: inline invalid-credentials (401) and network-error messages.
• Visibility: i18n'd badge — draft (neutral) / internal (amber) / public (green).
• All user-facing copy lives in en.json + sv.json; language switch persists to localStorage.

Testing & CI

• Vitest + RTL + MSW. test/setup.ts starts an MSW server; handlers.ts returns realistic responses typed against schema.d.ts. Coverage for M1:
  • API client + query hooks (success + error mapping).
  • Login flow: success → navigates; 401 → inline error.
  • Objects list: renders rows, pagination controls, empty + error states.
  • Object detail: renders fields + visibility; 404 state.
  • Language switch toggles copy.
  • RequireAuth redirects unauthenticated users to /login.
• CI (new web job): pnpm install → tsc typecheck → eslint → vitest run → vite build → bundle-size check (initial JS ≤ 150 KB gz).

Acceptance criteria (Milestone 1 "done")

1. pnpm dev + the running server: can log in, see a paginated object list, select a row, read its detail (incl. flexible-field values), switch sv/en, and log out.
2. Unauthenticated access to a protected route redirects to /login; a 401 mid-session bounces to /login.
3. cargo build -p server --features embed-web (after pnpm build) produces a binary that serves the SPA at / with working client-side routing; backend cargo test still passes without a built frontend.
4. web CI job green: typecheck, lint, tests, build, bundle-size within budget.
5. Later nav items are visible but disabled.

Out of scope / follow-ups

• Playwright e2e smoke (later milestone, once --seed data exists; relates to issue #14).
• Object create/edit/delete + dynamic field forms (Milestone 2).
• Any write operations from the UI (M1 is read-only beyond auth).