> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontend Architecture

> Key architectural decisions in the SvelteKit frontend — recording state, cross-tab coordination, and realtime updates.

## Persistent recording state

Recording state lives in a **module-level Svelte store** (`ui/src/lib/stores/activeRecording.ts`), not component state. This means a recording survives navigating away from the session page — only one recording may be active per browser tab.

`MediaRecorder` and the `getUserMedia` stream are non-reactive module singletons. Recording UI components are thin shells over that store; errors are keyed to the store's `errorSessionId` / `sessionId` so a different session's failure never leaks onto an unrelated session's page.

## Cross-tab coordination

All tabs coordinate via a shared `BroadcastChannel('kair_recording_status')`.

**Status sync messages** — keep `activeSessions.ts` in sync across every open tab:

* `recording_started`
* `recording_stopped`
* `recording_paused`

**Ownership messages** — resolve the `recording_owner_<sessionId>` `localStorage` flag's blind spot (the flag is shared by every tab of the same browser, so it can't distinguish "this tab owns it" from "a different tab of mine is recording"):

* `ownership_query` — broadcast on load to check if another tab is recording this session
* `ownership_ack` — reply from the owning tab
* `ownership_revoked` — sent when the owning tab stops

This determines whether to show "Continue Recording" (this tab already owns it) or a takeover prompt (another tab is recording).

### Organisation switch

`workspacesStore` (`ui/src/lib/stores/workspaces.ts`) and `sessionsStore` (`ui/src/lib/stores/sessions.ts`) are the single source for organisation-scoped lists. When the current organisation changes (a switch in this tab, a switch broadcast on `kair_org_context` from another tab, or the server reporting a different organisation when the tab becomes visible), `ui/src/lib/stores/orgContext.ts` refetches both through `refreshOrgScopedData()`; if that fails, both stores are emptied rather than left showing the previous organisation. `orgSwitching` is `true` from the user update until the refetch settles, and the sidebar and dashboard show their loading states while it is set so stale lists never flash up. The dashboard and its Contribute page additionally narrow the lists with `filterToActiveOrg` (`ui/src/lib/org/activeOrgScope.ts`), which keeps only workspaces whose `organisation_id` equals the current organisation, and their sessions, so organisation-less workspaces are hidden there.

## Dev panel

A dev-only `CommandCenterDevPanel` (mock sessions, intensity sliders, summary edge cases) is lazily imported in the root layout behind `import.meta.env.DEV`.

## Realtime instead of polling

Components never poll for state that changes rarely. They load over REST on mount and subscribe to a topic on the tab's single WebSocket (`ui/src/lib/realtime/`); on a pushed event or a `resync` they call their existing refresh function through a coalescing helper (`createCoalescedRefresh`, 250 ms debounce, single-flight). Local-only timers (countdowns, "now" ticks) are fine. Time-derived labels ("online", "last seen 3 min ago") read the 15 s `clock` store (`ui/src/lib/stores/clock.ts`) so they age on screen without refetching. Subscribe synchronously (in `onMount`/`$effect` before any `await`), or guard with a destroyed flag, so a component that unmounts mid-load can't leak a subscription. There is no polling fallback if the socket is down. See [Realtime](https://docs.kair.is/platform/realtime.md) for topics, events, the resync contract and how a recorder learns about Stop.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.