IMPORTANT

AI Context & Knowledge Heritage

• Subsystem: Architecture & Documentation / Core Docs / Frontend_State_Management
• Architecture: @docs ARCHITECTURE:Documentation
• Failure Path: Information drift, legacy terminology, or documentation mismatch.
• Observability: Traceability via execution/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.