App Architecture & Routes

The insigz single-page app shell, hash router, full route map, theme system, projects layer, store, shared state primitives, and accessibility.

Shell & boot

insigz app.html is a single-page app: pinned React 18 + Babel-standalone, a hash router, and a stack of text/babel component files. The root is wrapped:

<ErrorBoundary><ProjectProvider><CaseStoreProvider><App/></CaseStoreProvider></ProjectProvider></ErrorBoundary>

App resolves theme + mock auth, force-redirects unauthenticated users to /login, and renders one of three layouts:

Auth (/login, /register, /forgot) — standalone split-pane screens.
Settings (/settings/*) — full-bleed under the top nav with its own left sub-nav.
Standard shell — TopNav + main surface + the global chat host + the toast host.

A <ToastHost/> and a <CommandPalette/> are mounted in both the settings and standard layouts.

TopNav (in app-shell.jsx) renders: brand · ProjectSwitcher · the surface tabs · ⌘K search · theme toggle · notifications bell · user menu. The surface tabs use a priority-plus OverflowNav: it measures available width (hidden mirror row + ResizeObserver) and renders as many tabs as fit, collapsing the rest into a MORE ▾ dropdown that highlights when the active route lives inside it. Tabs come from activeProject.surfaces (Overview, Explore, Cases, Reports, Sources, Sessions, Workshop). Below the mobile breakpoint the whole nav becomes a hamburger drawer.

Full route map (hash-routed)

Route	Screen	File
`/login` · `/register` · `/forgot`	Auth split-pane	`app-screens.jsx`
`/overview` (default) · `/`	Project Overview (home)	`app-overview.jsx`
`/explore` · `/workspace`	Map workspace (live-ops) or Research workspace	`app-screens.jsx` / `app-research.jsx`
`/cases`	Cases list	`app-screens.jsx`
`/cases/:id`	Case detail (AsOf, hypothesis/events/entities)	`app-screens.jsx`
`/entities/:id`	Entity Inspector	`app-entity-inspector.jsx`
`/sources`	Sources (the fusion layer) list	`app-screens.jsx`
`/sources/onboard`	Ontology Agent onboarding wizard	`app-source-onboarding.jsx`
`/sources/:id`	Source inspect detail	`app-detail-views.jsx`
`/reports`	Reports list (Q7 three-origin draft flow)	`app-screens.jsx`
`/reports/:id`	Report view / editor	`app-detail-views.jsx`
`/sessions`	Wargame sessions list	`app-screens.jsx`
`/sessions/:id`	Session detail (phases, cells, faculty queue)	`app-detail-views.jsx`
`/workshop`	Workshop editors (3 tabs)	`app-workshop-editors.jsx`
`/workshop-canvas`	Original static workshop artboard (reference)	`product-artboards.jsx`
`/aar-drafting`	Staff AAR drafting (Q8-gated export)	`app-aar-drafting.jsx`
`/team-view`	Arena role previews (NATO/Hybrid/Civil + light)	`insigz app.html` + artboards
`/project` · `/project/*`	Project settings router	`app-project-settings.jsx`
`/projects` · `/projects/new`	Projects index · New Project wizard	`app-projects.jsx`
`/settings` → `/settings/account`	Org settings (redirects)	`app-settings.jsx`
`/settings/{account,team,tenants,data,canonical,api,security,notifications,billing,audit}`	Org settings sub-routes	`app-settings.jsx`

Route order matters: /sources/onboard is checked before /sources/:id; /sessions/:id and /reports/:id are startsWith checks after their list routes.

Theme system

Two coexisting palettes by intent:

tokens.css — CSS custom properties for all marketing pages + subpage.css consumers.
DARK_T / LIGHT_T JS theme objects in app-shell.jsx — for the app SPA and every JSX file (passed via ThemeCtx, read with useTheme() → { theme, setTheme, t }).

Invariant: the brand accent (#1F9D74 marketing / #62E1B6 dark-app accent) and the structural neutrals stay aligned across both. The app theme object exposes: void, base, raised, line, lineStrong, text, textSoft, muted, faint, accent, warn, alert, cool, mode, plus map-styling tokens.

The Projects layer (`app-projects.jsx`)

BLUEPRINTS — project templates (modes, map, source pack) — see 01-product-overview.md.
CATALOG — the org-level connector library (~21 feeds with family, connector type, rate); CATALOG_BY_ID + projectSources(project) enrich a project's source-id list into table rows with mock health.
SEED_PROJECTS — the 7 seed projects, persisted to localStorage('insigz-projects-v4'). A surface-policy override (TESTING_ALL_SURFACES_ON + applySurfacePolicy) currently forces all surfaces on for testing.
ProjectProvider / useProjects() — exposes projects, activeProject, setActiveId, createProject, updateProject, deleteProject.
ProjectSwitcher — top-nav dropdown (active project + org, switch, project settings, all projects, new project).
NewProjectWizard — 5-step: Identity → Region → Sources → Team → Review.

The store (`app-cases-store.jsx`)

CaseStoreProvider / useCaseStore() — project-keyed cases, reports, sessions; casesFor/reportsFor/sessionsFor(pid), caseById, addCase, addReport. Cases & reports persist to localStorage; sessions are seed-only.
NewCaseModal (priority + status) and ProjectReportModal (Q7 three-origin: stand-alone / derived-from-case / imported). Both fire success toasts on create.

Shared state primitives (`app-states.jsx`)

<Freshness ts> — relative-time chip with pulsing dot.
<AsOfControl asOf onChange> — LIVE (green pulse) / AS-OF (amber) chip (doctrine Q2).
<EmptyState> · <SkeletonTable> · <ErrorState variant> — the D/E/L/E view-state previews (variants: source-down, budget-cap, network, no-results, auth-revoked, generic). Used everywhere via the per-screen ViewToggle.

Command palette (`app-cmdk.jsx`)

⌘K / Ctrl+K global. Searches routes, recent cases, actions. Dispatched from the nav search stub.

Accessibility (`app/app-a11y.css`)

2px focus rings at 3:1 contrast on interactive elements; prefers-reduced-motion disables ambient animation; 44px minimum hit targets on mobile-targeted controls; skip-to-content link. Marketing pages get a parallel mobile stylesheet (app-mobile.css for the app; subpage.css/subpage.js for marketing, incl. the injected hamburger nav and the Docs sidebar disclosure).