> [!IMPORTANT]
> **AI Assist Note (Knowledge Heritage)**:
> This document is part of the "Sovereign Reality" documentation.
> - **@docs ARCHITECTURE:Documentation**
> - **Failure Path**: Information drift, legacy terminology, or documentation mismatch.
> - **Telemetry Link**: Cross-reference with `execution/parity_guard.py` results.
>
> ### AI Assist Note
> Automated governance and architectural tracking.
>
> ### 🔍 Debugging & Observability
> Traceability via `parity_guard.py`.

# ⚛️ Frontend & Client Architecture

> **@docs ARCHITECTURE:Interface**

The Tadpole OS Dashboard is a high-concurrency React 19 interface designed for low-latency observability and multi-monitor swarm management.

---

## 🏗️ Reactive Infrastructure: Zustand

Tadpole OS utilizes a decentralized **Zustand** store architecture to maintain a unitary source of truth across all components.

| Store | Responsibility |
|:--- |:--- |
| **`agent_store`** | Identity, telemetry, and capability status. |
| **`workspace_store`** | Mission clustering and RAG context management. |
| **`provider_store`** | Secure credential management (Vault) and model availability. |
| **`tab_store`** | Viewport orchestration and layout state. |

### Architectural Service Decoupling & Defensive State Management
- **Safe Store Injection & Defensive Access**: `workspace_service.ts` uses private initialization guards (`get_store()`) eliminating unhandled null dereferences (`workspace_store!`).
- **High-Entropy Cluster ID Generation**: Switched from truncated UUIDs to full 128-bit `crypto.randomUUID()` identifiers (`cl-${crypto.randomUUID()}`), eliminating collision vectors.
- **Optimistic State Rollback**: `update_budget` and `update_cluster_privacy` save previous state snapshots and automatically revert local store state upon backend API failure.
- **API Leakage Elimination**: Store actions delegate governance policy updates to `workspace_service.ts` and `system_api_service`, maintaining strict layer separation.

### Performance Optimization: Atomic Selectors
To prevent re-render fatigue, components utilize **Atomic Selectors**. Updating a single agent's token-burn count will not trigger a re-render of the entire agent grid.

---

## 🖇️ The "State-Preserved Detachment" Pattern

Tadpole OS implements a high-performance multi-window system using **React Portals**.

### 1. Unified React Tree
Detached windows (e.g., Swarm Visualizer, Terminal) are NOT independent application instances. They exist within the **same React tree** and share the same JavaScript heap.

### 2. Zero-Latency Sync
Because common state (Zustand) is shared directly in memory, telemetry updates at 10Hz are reflected across all monitor screens with zero IPC (Inter-Process Communication) overhead.

### 3. Dynamic Style Synchronization
A `MutationObserver` in the parent window monitors Tailwind and theme changes, automatically injecting new styles into the detached windows in real-time.

---

## ⚡ Performance Buffering: RAF Batching

During high-concurrency agent swarms, the engine may broadcast hundreds of log events per second.
- **Event Bus**: All incoming WebSocket telemetry is pushed into a non-reactive `ref` bus.
- **RAF Flush**: A `requestAnimationFrame` hook flushes these events to the React state exactly once per frames (60fps), ensuring a smooth, jank-free "living" dashboard.

---

## 🛠️ Connectivity: WebSocket Multiplexing

The dashboard maintains a single persistent `/ws` connection with the engine.
- **Binary Protocols**: High-speed telemetry (e.g., the Swarm Pulse) is broadcast via **MessagePack** binary headers for minimal bandwidth overhead.
- **Auth Handshake**: Authentication is handled via `Sec-WebSocket-Protocol` headers, preventing token exposure in URL logs.

[//]: # (Metadata: [Frontend_State_Management])
