From ca440c837bd602c82058a44f713adb6c147b7f78 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 30 Aug 2026 23:18:33 +0000
Subject: [PATCH] docs: add monorepo, UI components, state management and
 testing guides

Adds docs/monorepo.md (workspace layout, Turbo task graph, shared
tooling), apps/web/docs/components-ui.md (shared UI primitives
reference), apps/web/docs/concepts-state-management.md (provider tree,
Auth/Wallet contexts, ProtectedRoute), and apps/web/docs/testing.md
(Vitest setup, fake-indexeddb, WebCrypto, socket mocking).

Closes #544
Closes #568
Closes #572
Closes #573

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8SebNynWtmCebVq8tpgxS
---
 apps/web/docs/components-ui.md             | 242 +++++++++++++++++++++
 apps/web/docs/concepts-state-management.md | 179 +++++++++++++++
 apps/web/docs/testing.md                   | 211 ++++++++++++++++++
 docs/monorepo.md                           |  95 ++++++++
 4 files changed, 727 insertions(+)
 create mode 100644 apps/web/docs/components-ui.md
 create mode 100644 apps/web/docs/concepts-state-management.md
 create mode 100644 apps/web/docs/testing.md
 create mode 100644 docs/monorepo.md

diff --git a/apps/web/docs/components-ui.md b/apps/web/docs/components-ui.md
new file mode 100644
index 0000000..b44cc15
--- /dev/null
+++ b/apps/web/docs/components-ui.md
@@ -0,0 +1,242 @@
+# UI Primitives (`apps/web/src/components/ui/`)
+
+This document covers the shared UI primitives in `apps/web/src/components/ui/`: `Avatar`, `Badge`, `CopyButton`, `EmptyState`, `Modal`, `ProposalCard`, `SkeletonLoader`, and `Spinner`. For each component: its props, a usage example, whether it's presentational or stateful, any accessibility behavior implemented, and current test coverage. Test coverage was verified by grepping the whole repo for each component name inside `*.test.*` files — `ProposalCard.test.tsx` is the only test file found for any of these eight components.
+
+---
+
+## Avatar
+
+`apps/web/src/components/ui/Avatar.tsx`
+
+**Props**
+
+| Name | Type | Required | Default |
+|---|---|---|---|
+| `src` | `string` | No | `undefined` |
+| `fallback` | `string` | Yes | — |
+| `size` | `'sm' \| 'md' \| 'lg'` (maps to 24 / 36 / 48px) | Yes | — |
+| `online` | `boolean` | No | `undefined` (falsy) |
+
+`fallback` is also used to derive initials (via `getInitials`) and a deterministic background color (via a simple string hash → HSL hue) when no image is shown.
+
+**Usage**
+
+```tsx
+<Avatar src={user.avatarUrl} fallback={user.name} size="md" online={user.isOnline} />
+```
+
+**Type**: Stateful. Uses `useState` to track a `failedSrc` (so that if the image `onError`s, it falls back to the initials avatar instead of retrying), and `useMemo` to compute initials/color.
+
+**Accessibility**: The outer wrapper has `aria-label="Avatar for {fallback}"`. When an image is shown, its `alt` text is the same `ariaLabel`. The optional online indicator dot has its own `aria-label="Online"`.
+
+**Test coverage**: No test file today.
+
+---
+
+## Badge
+
+`apps/web/src/components/ui/Badge.tsx`
+
+**Props**
+
+| Name | Type | Required | Default |
+|---|---|---|---|
+| `variant` | `'default' \| 'success' \| 'warning' \| 'danger'` | No | `'default'` |
+| `children` | `React.ReactNode` | Yes | — |
+| `className` | `string` | No | `undefined` |
+
+**Usage**
+
+```tsx
+<Badge variant="success">Active</Badge>
+```
+
+**Type**: Presentational. A pure function component with no state, effects, or refs — just a `<span>` with variant-based Tailwind classes.
+
+**Accessibility**: None implemented beyond it being a plain inline text element (no `role` or `aria-*` attributes).
+
+**Test coverage**: No test file today.
+
+---
+
+## CopyButton
+
+`apps/web/src/components/ui/CopyButton.tsx`
+
+**Props**
+
+| Name | Type | Required | Default |
+|---|---|---|---|
+| `value` | `string` | Yes | — |
+| `className` | `string` | No | `''` |
+
+**Usage**
+
+```tsx
+<CopyButton value={wallet.address} className="ml-2" />
+```
+
+**Type**: Stateful. Uses `useState` to track a `copied` boolean.
+
+**Accessibility / copied feedback**: The button's `aria-label` and `title` swap between `"Copy address"` / `"Copy to clipboard"` and `"Copied address"` / `"Copied!"` based on the `copied` state. Clicking calls `navigator.clipboard.writeText(value)`; on success it sets `copied` to `true` and shows an animated checkmark icon (via `framer-motion`'s `AnimatePresence`, cross-fading from a Copy icon to a Check icon) in place of the copy icon. The `copied` state is reset back to `false` after **2000ms** (`setTimeout`), reverting to the copy icon/labels. While `copied` is `true`, clicking again is a no-op (`if (copied) return`). Clicks call `e.stopPropagation()` so the button can sit inside a clickable parent (e.g. a card) without triggering the parent's click handler. Clipboard failures are silently swallowed (empty `catch`).
+
+**Test coverage**: No test file today.
+
+---
+
+## EmptyState
+
+`apps/web/src/components/ui/EmptyState.tsx`
+
+**Props**
+
+| Name | Type | Required | Default |
+|---|---|---|---|
+| `icon` | `string` | Yes | — |
+| `title` | `string` | Yes | — |
+| `description` | `string` | Yes | — |
+| `action` | `{ label: string; onClick: () => void }` | No | `undefined` |
+
+**Usage**
+
+```tsx
+<EmptyState
+  icon="📭"
+  title="No proposals yet"
+  description="Create a proposal to get started."
+  action={{ label: 'New Proposal', onClick: openCreateModal }}
+/>
+```
+
+**Type**: Presentational. Pure function component, no state or effects.
+
+**Accessibility**: The icon `<div>` is marked `aria-hidden="true"` since it's decorative; the title/description are rendered as a semantic `<h3>`/`<p>` pair. The optional action renders as a real `<button type="button">`.
+
+**Test coverage**: No test file today.
+
+---
+
+## Modal
+
+`apps/web/src/components/ui/Modal.tsx`
+
+**Props**
+
+| Name | Type | Required | Default |
+|---|---|---|---|
+| `isOpen` | `boolean` | Yes | — |
+| `onClose` | `() => void` | Yes | — |
+| `title` | `string` | Yes | — |
+| `children` | `ReactNode` | Yes | — |
+
+**Usage**
+
+```tsx
+<Modal isOpen={isOpen} onClose={() => setIsOpen(false)} title="Confirm Execution">
+  <p>Are you sure you want to execute this proposal?</p>
+</Modal>
+```
+
+**Type**: Stateful. Uses `useState` for a three-phase visibility machine (`'closed' | 'open' | 'closing'`), `useRef` for the content element and for the element that had focus before opening, and several `useEffect`s to drive open/close transitions, focus handling, and body scroll locking. Renders via `createPortal` into `document.body`.
+
+**Accessibility**: This is the most accessibility-featured component in the set:
+- Root dialog `<div>` has `role="dialog"`, `aria-modal="true"`, and `aria-label={title}`.
+- **Focus trap**: on open, focus moves to the first focusable element inside the modal content (via a `FOCUSABLE` selector list covering links, buttons, inputs, textareas, selects, and `[tabindex]`). A `keydown` listener intercepts `Tab`/`Shift+Tab` at the first/last focusable elements and wraps focus back around, keeping focus inside the modal.
+- **Focus restoration**: the element focused before the modal opened (`prevFocus.current`) is refocused once the close animation finishes.
+- **Escape to dismiss**: the same `keydown` listener closes the modal (`onClose()`) on `Escape`.
+- **Backdrop click to dismiss**: the semi-opaque backdrop `<div>` has an `onClick={onClose}`.
+- **Body scroll lock**: `document.body.style.overflow` is set to `'hidden'` while open and restored on close/unmount.
+- A visible `Close` button in the header also has `aria-label="Close modal"`.
+- The content panel itself has `tabIndex={-1}` so it can programmatically receive focus without becoming part of natural tab order.
+
+**Test coverage**: No test file today.
+
+---
+
+## ProposalCard
+
+`apps/web/src/components/ui/ProposalCard.tsx`
+
+**Props**
+
+| Name | Type | Required | Default |
+|---|---|---|---|
+| `proposal` | `{ id: string; status: ProposalStatus; expiryLedger: number }` | Yes | — |
+| `currentLedger` | `number` | Yes | — |
+| `isMember` | `boolean` | Yes | — |
+| `onExecute` | `(id: string) => void` | Yes | — |
+| `onFinalize` | `(id: string) => void` | Yes | — |
+
+`ProposalStatus` is `'pending' | 'approved' | 'executed' | 'rejected' | 'expired'`.
+
+**Usage**
+
+```tsx
+<ProposalCard
+  proposal={{ id: '42', status: 'approved', expiryLedger: 1200 }}
+  currentLedger={1150}
+  isMember={true}
+  onExecute={(id) => executeProposal(id)}
+  onFinalize={(id) => finalizeProposal(id)}
+/>
+```
+
+**Type**: Stateful. Uses `useState` for `isCollapsed` (defaults to `true` for `executed`/`rejected` proposals) and `timeLeft` (a countdown string), plus a `useEffect` that recomputes the countdown immediately and then every 60 seconds via `setInterval` (cleared on unmount/dependency change). One ledger is treated as ≈5 seconds for the countdown math.
+
+Behavior notes: the status badge color is looked up from a `badgeColors` map keyed by status. The "Execute Withdrawal" button only renders when `status === 'approved' && isMember`. The "Finalize" button only renders when `status === 'expired'`. A collapse/expand toggle ("Show Past Details" / "Hide Details") only appears for `executed`/`rejected` proposals.
+
+**Accessibility**: None explicitly implemented — plain `<div>`/`<button>`/`<span>` elements with no `aria-*` attributes or semantic roles beyond native button/heading semantics (`<h3>`).
+
+**Test coverage**: Yes — `apps/web/src/components/ui/ProposalCard.test.tsx` (the only component in this folder with a dedicated test file). It covers: (1) the Execute button rendering only when `isMember` is true and status is `approved`, verified via `rerender` with `isMember={false}`; (2) the Finalize button rendering for `expired` status instead of the approve/execute controls.
+
+---
+
+## SkeletonLoader
+
+`apps/web/src/components/ui/SkeletonLoader.tsx`
+
+**Props**
+
+| Name | Type | Required | Default |
+|---|---|---|---|
+| `variant` | `'text' \| 'avatar' \| 'card'` | Yes | — |
+| `count` | `number` | No | `2` (internally clamped to the range 1–3; only used for `variant="text"`) |
+
+**Usage**
+
+```tsx
+<SkeletonLoader variant="card" />
+<SkeletonLoader variant="text" count={3} />
+```
+
+**Type**: Presentational. Pure function component — no state, effects, or refs. `count` is normalized by a plain helper function (`clampCount`), not stored as state.
+
+**Accessibility**: The `avatar` variant's placeholder `<div>` is marked `aria-hidden="true"`. The `text` and `card` variants have no explicit `aria-*` attributes. A global `<style jsx>` block defines the pulse animation and disables it under `prefers-reduced-motion: reduce` (falling back to a static `opacity: 0.7`).
+
+**Test coverage**: No test file today.
+
+---
+
+## Spinner
+
+`apps/web/src/components/ui/Spinner.tsx`
+
+**Props**
+
+| Name | Type | Required | Default |
+|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | No | `'md'` |
+| `label` | `string` | No | `undefined` |
+| `className` | `string` | No | `undefined` |
+
+**Usage**
+
+```tsx
+<Spinner size="sm" label="Loading proposals" />
+```
+
+**Type**: Presentational. Pure function component — no state or effects; size lookup is a plain object map.
+
+**Accessibility**: When `label` is provided, the spinner element gets `role="status"` and `aria-label={label}`, making it announced to screen readers. When `label` is omitted, it is instead marked `aria-hidden={true}` so assistive tech ignores it entirely. A global `<style jsx>` block defines the spin animation and disables it under `prefers-reduced-motion: reduce`.
+
+**Test coverage**: No test file today.
diff --git a/apps/web/docs/concepts-state-management.md b/apps/web/docs/concepts-state-management.md
new file mode 100644
index 0000000..53811d9
--- /dev/null
+++ b/apps/web/docs/concepts-state-management.md
@@ -0,0 +1,179 @@
+# Frontend State Management (`apps/web`)
+
+This document describes how client-side state is organized in the Next.js web app: the
+React context provider tree, what each context owns, the boundary between in-memory
+context state / per-route server state / IndexedDB-persisted state, and why there is no
+global store library.
+
+## ⚠️ Known duplication: three `AuthContext` implementations exist
+
+A grep for auth-related context code turns up **three separate implementations**, but
+only **one is actually wired up and used**. Read this section before touching auth code.
+
+| Location | Status |
+|---|---|
+| `src/components/auth/AuthContext.tsx` + `AuthProvider.tsx` + `useAuth.ts` | **Live.** Mounted in `src/app/layout.tsx` (the real root layout) and consumed throughout the app. |
+| `src/contexts/AuthContext.tsx` | **Dead code.** Defines its own `AuthContext`/`AuthProvider`/`useAuth` (a more elaborate wallet-challenge sign-in flow that depends on `useWallet`, `apiFetch`, `signWalletMessage`, `getOrCreateDeviceIdentity`). Not imported by any provider tree or any consumer (`grep -rn "contexts/AuthContext"` outside the file itself returns nothing). |
+| `src/lib/auth.tsx` | **Dead code, but wired into an unused file.** Defines yet another `AuthContext`/`AuthProvider`/`useAuth` pair. It is imported only by `src/app/providers.tsx`. |
+| `src/app/providers.tsx` | **Dead code.** Exports a `Providers` component that wraps `AuthProvider` from `lib/auth.tsx`. Nothing imports `Providers` — it is not referenced from `src/app/layout.tsx` or anywhere else in `src/app`. It looks like an abandoned/earlier attempt at composing providers, superseded by mounting providers directly in `layout.tsx`. |
+
+**The implementation that matters is `src/components/auth/*`.** It is imported by:
+`src/app/layout.tsx` (mounts `AuthProvider`), and consumed via `useAuth()` in
+`ConversationListSidebar.tsx`, `PushPermissionPrompt.tsx`, `treasury/ProposalCard.tsx`,
+`app/app/profile/page.tsx`, `app/app/conversations/[id]/page.tsx`,
+`app/app/treasury/page.tsx`, `app/app/devices/page.tsx`, and `components/auth/ProtectedRoute.tsx`.
+
+Everything below documents the **live** system (`components/auth/*` + `contexts/WalletContext.tsx`,
+mounted from `src/app/layout.tsx`). The two dead files (`contexts/AuthContext.tsx`,
+`lib/auth.tsx`) and the unused `app/providers.tsx` are noted only as cleanup candidates —
+do not build on them, and consider deleting them in a follow-up to avoid future confusion
+(e.g. an engineer importing `useAuth` from the wrong module and silently getting a
+context with a different shape — `token`/`loading` vs. `token`/`user`/`isLoading`/`signIn`/`signOut`).
+
+## Provider tree
+
+The real provider nesting happens in **`src/app/layout.tsx`** (the root layout), not
+`app/providers.tsx`:
+
+```tsx
+<WalletProvider>
+  <AuthProvider>
+    <ToastProvider>{children}</ToastProvider>
+  </AuthProvider>
+</WalletProvider>
+```
+
+Outer to inner: **Wallet → Auth → Toast → page tree**.
+
+Why this order matters:
+
+- **`WalletProvider` must be outermost (relative to Auth)** because nothing in the live
+  `AuthProvider` (`components/auth/AuthProvider.tsx`) actually depends on wallet state —
+  but the codebase's *other* (dead) auth implementation (`contexts/AuthContext.tsx`) does
+  call `useWallet()` inside its `signIn()` to get `publicKey`/`connect`. Wallet is placed
+  outside Auth so a wallet-driven sign-in flow can call into wallet state without a
+  provider-ordering error ("must be used within WalletProvider"). Root layout also
+  mounts `WalletProvider` above `AuthProvider` for the same reason `app/app/layout.tsx`
+  and `WalletConnectButton.tsx` can call `useWallet()` — wallet identity is the more
+  primitive, backend-independent piece of state (it only reflects whether a browser
+  extension/wallet is connected), while auth state is derived from a token that in
+  principle could depend on the connected wallet address.
+- **`AuthProvider` wraps `ToastProvider` and the rest of the app** because route
+  components (e.g. `ProtectedRoute`, page-level guards, sidebar/profile components) need
+  `useAuth()` available anywhere below it in the tree.
+- **`ToastProvider` is innermost** of the three because it is a pure UI-notification
+  mechanism with no dependency on auth or wallet state — it only needs to be available
+  wherever the app calls a toast, which is "everywhere," so its exact position relative
+  to Auth/Wallet has no functional effect; nesting it last simply keeps
+  auth/identity-related providers grouped together at the top.
+
+## Auth context (`src/components/auth`)
+
+**State held** (`AuthContext.tsx`):
+- `token: string | null` — the JWT/session token.
+- `loading: boolean` — true until the initial token read from storage has completed.
+
+**Actions exposed** (`useAuth()` from `useAuth.ts`):
+- `setToken(token: string)` — persists the token to `localStorage` under three legacy/alias
+  keys (`clicked_token`, `clicked.jwt`, `auth_token`) and updates state.
+- `clearToken()` — removes the token from all three storage keys and clears state (sign-out).
+
+**Initialization** (`AuthProvider.tsx`): on mount, reads the first present value across
+the three `localStorage` keys, and defers setting it via `requestAnimationFrame` before
+flipping `loading` to `false`. This means auth state is **not known synchronously on
+first render** — every consumer that gates rendering on auth must wait for `loading`.
+
+**Consumers** (via `useAuth()`):
+- `components/auth/ProtectedRoute.tsx` — route gating (see below).
+- `components/conversations/ConversationListSidebar.tsx`, `components/PushPermissionPrompt.tsx`,
+  `components/treasury/ProposalCard.tsx` — read `token`/`loading` to decide whether to
+  fetch user-scoped data or show authenticated UI.
+- `app/app/profile/page.tsx`, `app/app/conversations/[id]/page.tsx`,
+  `app/app/treasury/page.tsx`, `app/app/devices/page.tsx` — page-level use of the token
+  (e.g. to authorize API calls).
+
+## Wallet context (`src/contexts/WalletContext.tsx`)
+
+**State held:**
+- `publicKey: string | null` — the connected wallet's public key, or `null` if disconnected.
+
+**Actions exposed** (`useWallet()`):
+- `connect(): Promise<string>` — calls `requestWalletAccess()` (Freighter wallet integration
+  in `src/lib/freighter`), stores and returns the resulting public key.
+- `disconnect(): void` — clears `publicKey`.
+
+**Consumers** (via `useWallet()`):
+- `components/wallet/WalletConnectButton.tsx` — the wallet connect/disconnect UI with an
+  address dropdown (copy address, edit profile, disconnect).
+- `app/app/layout.tsx` — the authenticated app shell's sidebar wallet button.
+- The dead `contexts/AuthContext.tsx` also calls `useWallet()`, which is why `WalletProvider`
+  is deliberately mounted above `AuthProvider` even though the live `AuthProvider` doesn't
+  need it — see "Provider tree" above.
+
+Note: wallet connection state is entirely in-memory (`useState`), not persisted — a page
+reload requires reconnecting the wallet, unlike the token, which is persisted to `localStorage`.
+
+## `ProtectedRoute` (`src/components/auth/ProtectedRoute.tsx`)
+
+`ProtectedRoute` wraps a page's children and takes a `mode: 'authenticated' | 'unauthenticated'`
+prop:
+
+- `mode="authenticated"`: if there is no `token`, redirects away from the protected page.
+- `mode="unauthenticated"`: if there **is** a `token`, redirects away (used on the public
+  landing page, `src/app/page.tsx`, to bounce already-authenticated users into the app).
+
+**Redirect mechanism:** `router.replace(...)` from `next/navigation` (`useRouter()`),
+inside a `useEffect`. `replace` (not `push`) is used so the redirect doesn't leave the
+gated page in browser history. Concretely: `authenticated` mode redirects to `/`;
+`unauthenticated` mode (used on the landing page) redirects to `/app`.
+
+**Loading gate:** the effect — and the render — first checks `loading` from `useAuth()`.
+While `loading` is `true`, `ProtectedRoute` renders `null` and does not redirect at all.
+This exists because `AuthProvider`'s initial token read is asynchronous (deferred one
+animation frame) — on first render, before `localStorage` has been checked, `token` is
+still `null` even for an already-authenticated user. Without the `loading` gate,
+`ProtectedRoute` would see `token === null` on that first render and redirect an
+authenticated user away before their real token is loaded — a visible
+redirect/flash-of-wrong-content. Gating on `loading` ensures the redirect decision is
+only made once the real auth state is known.
+
+## The three layers of client state
+
+1. **React context state (in-memory, per-session UI state)** — `AuthContext` (token,
+   loading flag) and `WalletContext` (publicKey). Lives only in memory for the life of
+   the tab; reconstructed on reload by re-reading `localStorage` (auth) or requiring a
+   fresh wallet connection (wallet). This is the layer for "what is true about the
+   current session right now" that many components need without prop-drilling.
+
+2. **Server state fetched per route/page** — most data (conversations, treasury
+   proposals, profile, devices) is fetched directly in page/component code via `fetch`/
+   `apiFetch` calls (see `src/lib/api.ts` and usage in `app/app/*` pages) rather than
+   being normalized into a global client store. Each page is responsible for fetching
+   the data it needs, using the `token` from `AuthContext` to authorize the request.
+   There is no client-side cache/store (no React Query, SWR, RTK Query, etc. observed)
+   — data is refetched per navigation/mount.
+
+3. **IndexedDB-persisted state** — used specifically for data too large, sensitive, or
+   structured for `localStorage`/React state:
+   - `src/lib/cryptoStore.ts`, `src/lib/prekeyStore.ts`, `src/lib/sessionStore.ts` — raw
+     `indexedDB.open(...)` usage for E2E-encryption key material and Signal-style ratchet
+     session state (device identity, prekeys, sessions).
+   - `src/lib/search/db.ts` — uses the `idb` package (`openDB`/`IDBPDatabase`) for a local
+     search index.
+
+   These are deliberately kept **out of React context** — they hold cryptographic
+   material and a search index, neither of which needs to trigger re-renders or be
+   read synchronously on every render; consumers call into these modules imperatively
+   (e.g. during sign-in or when indexing/searching) rather than subscribing to them as
+   context.
+
+## Why no global store library (Redux/Zustand/etc.)
+
+`package.json` has no Redux, Zustand, Jotai, Recoil, or MobX dependency — only `idb` for
+IndexedDB access. This tracks with the shape of the app's actual state needs: there are
+exactly two pieces of cross-cutting session state (auth token, wallet public key), each
+naturally scoped to a single React context with a handful of actions; everything else is
+either page-local `useState` (e.g. `WalletConnectButton`'s dropdown/connecting/error
+state) or server data fetched per route with no need for cross-route sharing or
+client-side caching. Two contexts plus a lib-level IndexedDB layer covers the requirement
+without introducing a general-purpose store and its associated boilerplate.
diff --git a/apps/web/docs/testing.md b/apps/web/docs/testing.md
new file mode 100644
index 0000000..473d065
--- /dev/null
+++ b/apps/web/docs/testing.md
@@ -0,0 +1,211 @@
+# Web app test setup
+
+This documents how tests are configured and run in `apps/web`, and the
+recurring patterns used for IndexedDB, WebCrypto, and network/socket code.
+
+## Runner config
+
+`apps/web/vitest.config.ts`:
+
+```ts
+export default defineConfig({
+  resolve: {
+    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
+  },
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    setupFiles: ['./src/test/setup.ts'],
+  },
+});
+```
+
+- **environment: `node`** — tests run without jsdom/happy-dom. There is no
+  real DOM, `window`, or browser IndexedDB; anything DOM-shaped a test needs
+  has to be faked explicitly (see below).
+- **include: `src/**/*.test.ts`** — only `.test.ts` files under `src/` are
+  picked up (not `.test.tsx`, so component tests aren't part of this glob
+  today).
+- **setupFiles**: `./src/test/setup.ts` runs once before the test files load.
+
+### `src/test/setup.ts`
+
+```ts
+import { webcrypto } from 'node:crypto';
+
+// polyfill window/self as aliases for globalThis (environment: 'node' has neither)
+if (!('window' in globalScope)) { ... globalScope.window = globalThis ... }
+if (!('self' in globalScope)) { ... globalScope.self = globalThis ... }
+
+// polyfill WebCrypto using Node's native implementation
+if (!globalScope.crypto) { ... globalScope.crypto = webcrypto ... }
+
+// polyfill base64 helpers Node doesn't have globally
+if (typeof globalScope.btoa !== 'function') { ... }
+if (typeof globalScope.atob !== 'function') { ... }
+```
+
+It installs four things, each guarded so it only patches what's missing:
+`window`/`self` as aliases for `globalThis`, `globalThis.crypto` from
+`node:crypto`'s `webcrypto` export, and `btoa`/`atob` shims backed by
+`Buffer`. This is what lets browser-shaped crypto and encoding code
+(`crypto.subtle...`, `btoa(...)`) run unmodified under Node.
+
+### Running tests
+
+Root test script (`apps/web/package.json`): `"test": "vitest run"`.
+
+To run the whole web suite:
+
+```sh
+pnpm --filter web test
+```
+
+To run a single file, pass the path through to the Vitest CLI:
+
+```sh
+pnpm --filter web test -- src/lib/crypto.test.ts
+# or, from apps/web directly:
+pnpm vitest run src/lib/crypto.test.ts
+```
+
+## IndexedDB: fake-indexeddb and resetting between tests
+
+Modules under `src/lib/search/` (`db.ts`, used by `db.test.ts` and
+`searchIntegration.test.ts`) persist to a real IndexedDB API, which doesn't
+exist in the Node test environment. Those test files import
+`'fake-indexeddb/auto'`, which installs an in-memory IndexedDB implementation
+onto the global scope before anything else in the file runs:
+
+```ts
+// apps/web/src/lib/search/db.test.ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import 'fake-indexeddb/auto';
+import { openDB } from 'idb';
+import { putMessages, getAllMessages, getMessagesByConversation, clearAll } from './db';
+
+describe('Local Encrypted Message Cache (#357)', () => {
+  beforeEach(async () => {
+    await clearAll();
+  });
+  ...
+});
+```
+
+`fake-indexeddb/auto` gives every test file in the process the same
+in-memory database — it is **not** reset automatically between test cases.
+Both `db.test.ts` and `searchIntegration.test.ts` call the module's own
+`clearAll()` in `beforeEach` to wipe stored records before each test runs.
+
+`identity-persistence.test.ts` (`src/lib/__tests__/identity-persistence.test.ts`)
+follows the same shape against a different store (`cryptoStore`, which wraps
+`idb`), clearing both before *and* after each test, and also closing the DB
+handle:
+
+```ts
+describe('Identity Key Persistence (Fixed)', () => {
+  beforeEach(async () => {
+    await cryptoStore.clear();
+  });
+
+  afterEach(async () => {
+    await cryptoStore.clear();
+    cryptoStore.closeDb();
+  });
+  ...
+});
+```
+
+**Why resetting matters**: these stores hold identity/ECDH key material
+(`cryptoStore`) and decrypted message plaintext cached at rest
+(`search/db.ts`). Because `fake-indexeddb` persists in memory for the life
+of the test process (not per-file or per-test), a private key generated or
+a message cached in one test would otherwise still be present — and
+readable — in the next test case, silently changing its inputs and letting
+key material or plaintext leak across unrelated tests. `db.test.ts` even has
+a dedicated test asserting the raw stored record contains no `plaintext`
+field, which only means something if the store was empty going in.
+
+## WebCrypto: real Node webcrypto, round-trip as the assertion
+
+Vitest's `environment: 'node'` has no browser `crypto.subtle`. `setup.ts`
+gives every test `globalThis.crypto = require('node:crypto').webcrypto`, so
+crypto code under test runs against a real, spec-compliant WebCrypto
+implementation rather than a mock — no algorithm behavior is faked.
+
+`crypto.test.ts` additionally stubs it explicitly per test (defensive
+against other tests mutating globals via `vi.stubGlobal`):
+
+```ts
+beforeEach(() => {
+  vi.stubGlobal('crypto', webcrypto);
+  vi.stubGlobal('atob', (value: string) => Buffer.from(value, 'base64').toString('binary'));
+  vi.stubGlobal('btoa', (value: string) => Buffer.from(value, 'binary').toString('base64'));
+});
+```
+
+The tests' meaningful assertion is not "the function didn't throw" — it's a
+full round trip: encrypt with the code under test, then independently
+decrypt (often with a hand-rolled decryptor using the same primitives) and
+assert the recovered plaintext equals the original:
+
+```ts
+// apps/web/src/lib/crypto.test.ts
+it('round-trips a message for a single recipient without a backend', async () => {
+  const recipient = await crypto.subtle.generateKey(
+    { name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveKey'],
+  );
+  const recipientPublicKey = new Uint8Array(await crypto.subtle.exportKey('raw', recipient.publicKey));
+
+  const ciphertext = await sealedBoxEncrypt('hello from clicked', bytesToB64(recipientPublicKey));
+  const plaintext = await decryptSealedBox(ciphertext, recipient.privateKey);
+
+  expect(plaintext).toBe('hello from clicked');
+  expect(b64ToBytes(ciphertext).length).toBeGreaterThan(77);
+});
+```
+
+`signalClient.test.ts` uses the same principle at a higher level: instead of
+decrypting, it asserts on protocol properties that only hold if the
+underlying Double Ratchet/X3DH math is correct — e.g. the same plaintext
+encrypted twice to the same device must produce different ciphertext
+(`c1).not.toBe(c2)`, ratchet advanced), and a session that fails to
+configure must reject rather than silently produce bad ciphertext.
+
+## Socket client: no dedicated mock today
+
+The socket client lives at `apps/web/src/lib/socket.ts`
+(`import { io, Socket } from 'socket.io-client'`) and is consumed by
+`useSocket.ts`, `useMessageHistory.ts`, `useInboundPipeline.ts`,
+`realtime.ts`, and `MessageThread.tsx`. As of this writing there is **no**
+`*.test.ts` file for `socket.ts`/`useSocket.ts`, and no `vi.mock('socket.io-client', ...)`
+anywhere in `apps/web/src` — the `include` glob (`src/**/*.test.ts`) also
+excludes `.tsx` component tests entirely, so `MessageThread.tsx` isn't
+exercised by this suite either.
+
+If/when a socket-dependent unit is tested, the established codebase pattern
+for isolating a real dependency is `vi.mock` combined with a fake
+implementation swapped in via `vi.stubGlobal`/dependency injection — see
+`signalClient.test.ts`, which avoids network/IO entirely by injecting a
+`FetchKeyBundle` function (`configureSignalClient({ myIdentity, fetchKeyBundle })`)
+instead of hitting a real backend, and `usePushSubscription.test.ts`, which
+stubs `fetch` globally rather than mocking a client module:
+
+```ts
+// apps/web/src/hooks/usePushSubscription.test.ts
+function mockFetchOnce(response: { ok: boolean; json: () => Promise<unknown> }) {
+  vi.stubGlobal('fetch', vi.fn().mockResolvedValue(response as unknown as Response));
+}
+```
+
+A `socket.io-client` mock would follow the same shape: `vi.mock('socket.io-client', () => ({ io: vi.fn(() => fakeSocket) }))`
+where `fakeSocket` is a minimal `{ on, off, emit, connect, disconnect }`
+object the test controls — but that pattern does not exist in this codebase
+yet, so nothing here should be taken as an existing, working example.
+
+Similarly, **`usePushSubscription.test.ts` does not exercise
+`navigator.serviceWorker`** — it only covers `fetchVapidPublicKey()`, a
+plain `fetch` wrapper, via `vi.stubGlobal('fetch', ...)`. There is no
+existing fake for `navigator.serviceWorker.register(...)` in this suite;
+`environment: 'node'` means `navigator` isn't defined at all unless a test
+polyfills it itself.
diff --git a/docs/monorepo.md b/docs/monorepo.md
new file mode 100644
index 0000000..57c02ce
--- /dev/null
+++ b/docs/monorepo.md
@@ -0,0 +1,95 @@
+# Monorepo Guide
+
+This is the top-level, cross-cutting guide to how this repository is organized and tooled.
+Each app also has its own `docs/` subfolder (`apps/web/docs`, `apps/backend/docs`,
+`apps/ai_agent/docs`, `contracts/docs`) for app-specific documentation — this file only
+covers the workspace layout and shared tooling that spans all of them.
+
+## Repository layout (one level deep)
+
+```
+.
+├── .github/          CI workflows / GitHub configuration
+├── apps/             pnpm workspace packages (see below)
+├── contracts/        Rust/Cargo workspace — Soroban smart contracts for Stellar
+├── docs/             top-level docs (architecture, runbooks, security, this file)
+├── infra/            local infrastructure — infra/docker-compose.yml (Postgres, Redis)
+├── scripts/          repo-wide scripts (load testing, crypto-dep auditing, dev helpers)
+├── src/              shared/top-level components (src/components/ui)
+├── Makefile          convenience targets that wrap pnpm/turbo/cargo commands
+├── package.json       root scripts + pinned shared devDependencies (turbo, prettier, ...)
+├── pnpm-workspace.yaml defines the pnpm workspace package globs
+└── turbo.json         Turborepo task graph (build/dev/lint)
+```
+
+### `apps/` (one level deeper)
+
+| Directory | Purpose |
+|---|---|
+| `apps/web` | Next.js 16 / React 19 frontend. Own `package.json`, `eslint.config.mjs`, `vitest.config.ts`. |
+| `apps/backend` | Node/TypeScript backend. Drizzle ORM, own `eslint.config.js`, tested with vitest. |
+| `apps/ai_agent` | Next-gen AI agent app, written in Python (`pyproject.toml` / `uv.lock`) — not a pnpm package. |
+| `apps/tests` | Top-level test suite directory (e.g. `apps/tests/routes/conversations.test.js`) sitting outside the individual app packages. |
+
+## Root scripts vs. per-app scripts
+
+Run a **root script** when you want the action to apply across the whole workspace, orchestrated by Turborepo:
+
+- `pnpm dev` — `turbo run dev`, starts every app's dev process.
+- `pnpm build` — `turbo run build`, builds every app in dependency order.
+- `pnpm lint` — `turbo run lint`, lints every app.
+
+Use `pnpm --filter <app> <script>` when working on a single app (faster inner loop, no need to
+spin up/build unrelated apps), e.g. `pnpm --filter backend db:migrate` or `pnpm --filter web dev`.
+The Makefile's `migrate` target is an example of this: `pnpm --filter backend db:migrate`.
+
+`apps/ai_agent` (Python) and `contracts` (Rust) are outside the pnpm/turbo graph entirely — they're
+driven with their own native tooling (`uv`, `cargo`), not `pnpm --filter`.
+
+## Turborepo task graph
+
+Defined in `turbo.json`:
+
+- **`build`** — `dependsOn: ["^build"]`, meaning a package's `build` task only runs after the
+  `build` tasks of all packages it depends on have completed (build dependencies first). Outputs
+  `.next/**` (excluding `.next/cache/**`) and `dist/**` are cached by Turborepo — if inputs haven't
+  changed, a cached result is replayed instead of rebuilding.
+- **`dev`** — `cache: false`, `persistent: true`. Dev servers are long-running processes, so they
+  are never cached and are marked persistent so Turbo knows not to wait for them to exit.
+- **`lint`** — `dependsOn: ["^lint"]`, same upstream-first ordering as `build`, but lint output
+  isn't declared as cacheable output in this config.
+
+In short: `build` and `lint` respect the dependency graph and `build` is content-cached; `dev`
+always runs fresh and never exits.
+
+## Shared root tooling
+
+- **Prettier**: `pnpm format` (`prettier --write "**/*.{ts,tsx,md,json}"`) and `pnpm format:check`
+  (`prettier --check`, same glob) apply formatting across the entire workspace, driven by the
+  shared root `.prettierrc.json` and `.prettierignore`. The root `package.json` pins
+  `"prettier": "3.9.1"` exactly (no `^`/`~`), so every app formats with the identical Prettier
+  version regardless of how pnpm hoists dependencies — no per-app Prettier version drift.
+- **ESLint**: there is **no root ESLint config**. Each app configures its own linting
+  independently (`apps/web/eslint.config.mjs`, `apps/backend/eslint.config.js`), unlike Prettier
+  which is centralized.
+
+## Why `contracts` is listed in the pnpm workspace
+
+`pnpm-workspace.yaml` lists `contracts` as a package glob alongside `apps/*`, but `contracts/`
+is a Cargo workspace (Soroban smart contracts for Stellar), not a JS/TS package — there is no
+`package.json` anywhere under `contracts/`. As a result it contributes no package to the actual
+pnpm workspace (pnpm only picks up directories that contain a `package.json`) and it does not
+appear in the Turborepo task graph — `turbo run build`/`lint` never touch it.
+
+In practice `contracts` is built, tested, and deployed independently through its own Rust
+tooling, orchestrated from the root `Makefile`:
+
+- `make test` runs `pnpm --filter backend test` for JS/TS **and separately** `cd contracts && cargo test` for the Soroban contracts.
+- `make deploy-contracts` runs the shell scripts in `contracts/scripts/` (`deploy_token_transfer.sh`, `deploy_group_treasury.sh`) directly.
+- `make lint` only runs `pnpm lint` (Turbo) — contract linting isn't wired into that target.
+
+So the `contracts` entry in `pnpm-workspace.yaml` doesn't wire Cargo into the pnpm/Turbo graph;
+it appears to be present for repo-organization / tooling-recognition purposes (e.g. so pnpm
+doesn't need a separate exclusion and so editors/tools resolve `contracts` as a recognized
+workspace root), while all real build/test/lint/deploy orchestration for it happens through
+Cargo and the Makefile, not through `pnpm`/`turbo`.