Frontend Productionization

Taking the prototype (React-in-Babel, single HTML files) to a production frontend without losing the design system.

From prototype to product

• Bundle: Vite + React + TypeScript (decided D4). Keep the existing component structure; port .jsx → .tsx.
• Design system: lift tokens.css + the theme objects into a real token package; the dark/light themes and the control-plane owner-blue accent stay.
• State/data: replace mock stores (localStorage, seed arrays) with the typed SDK (packages/sdk) hitting api; use TanStack Query for fetching/caching; keep optimistic UI where the prototype has it.
• Auth: replace mock sign-in with the real IdP flow (security/40) — redirect to SSO, store the session cookie, attach JWT to API calls.
• Realtime: subscribe to the WebSocket (backend/61); on a notify, invalidate the relevant query.
• Two apps: web (tenant app) and control-web (insigz Control) build separately, deploy separately (control-web is owner-only, behind the internal IdP).

The Claude cutover (the most disruptive change)

The prototype calls window.claude.complete in the browser; the production security model is server-side-only Claude (32, 42). Concrete cutover:

1. Delete every window.claude.complete call.
2. Route chat through POST /chat/messages on api, consuming the SSE stream (D6).
3. Keep the prototype’s nice token-reveal UX — now driven by real streamed tokens instead of a simulation.
4. Citations in the stream become clickable provenance links once the turn validates (31, 80). The browser never holds the Claude key.

Routing migration

The prototype uses hash routing; move to history routing deliberately, mapping the existing route table so deep links/bookmarks keep working (add redirects from #/... to /...).

What carries over unchanged

The whole visual language, the surfaces, the chat-first widget engine (launch/form/decision), the journey rail, the Entity Network renderer, Pattern-of-Life, and the control-plane screens — they're already built; productionization is wiring them to real data + auth + bundling, not a redesign.

Quality gates

• TypeScript strict; component tests (Vitest/RTL); E2E (Playwright) covering the critical flows (login, explore, case→report, provision).
• A11y: keyboard nav, focus management, contrast (the tokens already target this).
• CSP, SRI, no inline secrets; the frontend never sees the Claude key (server-side only).

Decided

• Vite SPA (D4); history routing (migrate from hash); TanStack Query for data.
• SDK generation: packages/sdk is regenerated from the OpenAPI spec (81) in CI on merge; the frontend imports it.

Gaps to close

• Define the component-test + E2E coverage targets and the CI gate.
• Confirm the hash→history redirect map against the prototype’s route table.