Client State Management
Relevant source files
The following files were used as context for generating this wiki page:
- GEMINI.md
- README.md
- CLAUDE.md
- AGENTS.md
- [design-system/HEX-YT-INTEL Design System (1)/README.md](https://github.com/Hex-Tech-Lab/hex-yt-intel/blob/2cca14edaf01ee2f92498e26c84151ce7dcccd5f/design-system/HEX-YT-INTEL%20Design System%20(1)/README.md)
- [design-system/HEX-YT-INTEL Design System (1)/SKILL.md](https://github.com/Hex-Tech-Lab/hex-yt-intel/blob/2cca14edaf01ee2f92498e26c84151ce7dcccd5f/design-system/HEX-YT-INTEL%20Design System%20(1)/SKILL.md)
Client State Management in the HEX-YT-INTEL project is governed by a strict architectural perimeter designed to maintain a high production bundle compression ratio (89%) and ensure compatibility with the Edge Runtime. The project utilizes a "Hexagonal Lite" (Ports & Adapters) pattern, where the presentation layer consists of pure, stateless components, and state logic is isolated within dedicated stores.
The primary technologies used for client-side state and validation are Zustand (v5.0.13) and Zod (v4.4.3), which are kept strictly aligned to ensure a secure state perimeter.
Sources: GEMINI.md:32-34, design-system/HEX-YT-INTEL Design System (1)/README.md:12-14
Architectural Principles
The project enforces a Hexagonal Lite + Domain-Driven Design (DDD) pattern. This architecture mandates that the presentation layer owns no state and acts as a stateless adapter.
Hexagonal Lite (Ports & Adapters)
- Presentation Layer: Components are 100% stateless React 19 adapters. They receive data, status unions, and callbacks via props.
- State Isolation: State is managed in stores (e.g.,
useAnalysisStore,useChatStore,useVideoStore) which act as the central source of truth. - Banned Patterns: The use of
useState,useEffect, or directfetchcalls within presentation components is strictly forbidden to maintain architectural purity.
Hybrid Edge Symphony (ADR 005)
State management also coordinates with the "Hybrid Edge Symphony," a multi-cloud flow that handles authentication, LLM streaming, and cryptographically signed data persistence.
Sources: GEMINI.md:144-155, design-system/HEX-YT-INTEL Design System (1)/README.md:16-18, CLAUDE.md:14-18
State and Data Flow
The following diagram illustrates the flow of state from the external Edge infrastructure through the state stores to the stateless UI components.
The diagram shows how real-time data from Server-Sent Events (SSE) updates the specialized Zustand stores, which then pass data and status as props to the stateless UI.
Sources: GEMINI.md:83-88, design-system/HEX-YT-INTEL Design System (1)/README.md:12-14, README.md:24-28
Core State Modules
The client state is divided into specific domain-driven stores. While the full implementation of individual stores (Analysis, Chat, Video) is managed via Zustand, they share common constraints and patterns.
Store Constraints and Standards
| Feature | Implementation / Rule |
|---|---|
| State Library | Zustand v5.0.13 |
| Validation | Zod v4.4.3 |
| Persistence | Chat persistence is managed to survive rehydration |
| Streaming | Stores must handle "streaming" status for the signature scope-ring motion |
| Auth Integration | Stores interact with Supabase client for authenticated requests |
Sources: GEMINI.md:32-34, 137-138, design-system/HEX-YT-INTEL Design System (1)/SKILL.md:26-28
The Streaming Lifecycle
State management is critical during the video synthesis process. The system transitions through specific status values that trigger UI changes, such as the rotating cyan scope-ring.
This sequence highlights the reactive relationship between the streaming hook, the Zustand store, and the resulting UI state.
Sources: design-system/HEX-YT-INTEL Design System (1)/README.md:78-83, AGENTS.md:23-26, CLAUDE.md:14-18
Dependency Guardrails
To maintain a 10x development velocity and prevent bundle bloat, specific libraries are permanently banned from the state and UI perimeter.
- Banned State/Auth:
next-auth(replaced by native SupabasegetSupabaseClientWithAuth()). - Banned UI/Styling: Material-UI (
@mui/material), Emotion, and any runtime CSS-in-JS injection engines. - Required Infrastructure: Node.js 24.16.0 and pnpm 11.1.3 must be used for all build and state-related operations.
Sources: GEMINI.md:38-48
Conclusion
Client State Management in HEX-YT-INTEL is a disciplined implementation of the Hexagonal Lite pattern. By strictly separating stateless presentation from Zustand-managed domain logic and utilizing a hybrid edge infrastructure for real-time updates, the system achieves high performance and architectural consistency across the Synthesis Console.