State Management
Relevant source files
The following files were used as context for generating this wiki page:
State management in the GoHighLevel Clone project is architected using a dual-layer approach that separates client-side UI state from server-side data synchronization. The system utilizes Zustand for lightweight, predictable client state and TanStack Query (React Query) for managing asynchronous server state, caching, and background synchronization.
The architecture ensures that complex UI interactions—such as visual workflow building, drag-and-drop Kanban boards, and multi-step forms—remain performant while maintaining data integrity across the application. Sources: FRONTEND_IMPLEMENTATION_SUMMARY.md, DDD_IMPLEMENTATION_REPORT_SPEC_FRN_001.md
State Management Architecture
The project employs a clear separation of concerns between different types of state. Local UI state is handled within components, global client state is managed via Zustand stores, and server-side data is handled by TanStack Query.
The diagram illustrates the flow where Zustand manages immediate user interactions and local persistence, while TanStack Query mediates between the stores and the backend API. Sources: FRONTEND_IMPLEMENTATION_SUMMARY.md, frontend/QUICK_REFERENCE.md
Client-Side State (Zustand)
The application uses specific Zustand stores to manage domain-specific logic. These stores often utilize the persist middleware to ensure data survives page reloads. Sources: CRM_FRONTEND_SUMMARY.md, DDD_IMPLEMENTATION_REPORT_SPEC_FRN_001.md
Workflow & Canvas Stores
The Workflow store manages the overall metadata and status of a workflow, while the Canvas store handles the complex state required for the visual builder, including node positions and history.
| Store | Purpose | Key Features |
|---|---|---|
workflow-store.ts | Manages workflow lifecycle and metadata. | Draft auto-save, unsaved changes tracking, persistence. |
canvas-store.ts | Manages visual builder elements (React Flow). | Nodes, edges, viewport state, undo/redo history (50 steps). |
Sources: frontend/src/lib/stores/workflow-store.ts, frontend/src/lib/stores/canvas-store.ts, FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md
CRM Store
The CRM store handles state for contacts, deals, and tasks. It includes logic for filtering, pagination, and multi-select bulk actions. Sources: frontend/src/lib/stores/crm-store.ts, CRM_FRONTEND_SUMMARY.md
This diagram represents the relationship between the Workflow metadata and the visual Canvas state. Sources: frontend/src/lib/stores/canvas-store.ts, frontend/src/lib/stores/workflow-store.ts
Server State (TanStack Query)
TanStack Query is used as the primary data fetching and caching layer. It handles background refetching, request deduplication, and optimistic updates. Sources: FRONTEND_IMPLEMENTATION_SUMMARY.md, frontend/QUICK_REFERENCE.md
Key Implementation Details
- Caching Strategy: Default stale time of 5 minutes.
- Error Handling: Integrated with toast notifications for global feedback.
- Provider: Configured in
src/app/providers.tsx.
Sources: DDD_IMPLEMENTATION_REPORT_SPEC_FRN_001.md:115-125, frontend/QUICK_REFERENCE.md
Specialized Logic: Undo/Redo System
The canvas-store.ts implements a history buffer to support undo/redo functionality within the visual builder. It maintains past and future stacks to store snapshots of the nodes and edges.
The undo/redo system allows for a 50-step history buffer. Sources: frontend/src/lib/stores/canvas-store.ts, FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md
Persistence and Auto-Save
The Workflow module includes a 30-second auto-save interval and draft management. Unsaved changes are tracked via the hasUnsavedChanges boolean in the Zustand store, which triggers a navigation guard if the user attempts to leave the page with pending edits. Sources: FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md, frontend/src/lib/stores/workflow-store.ts
Draft Management Table
| Action | Mechanism | Frequency |
|---|---|---|
| Auto-Save | Interval-based save to Local Storage | Every 30 seconds |
| Manual Save | Ctrl+S or UI Button | On demand |
| Draft Recovery | Zustand Persist Middleware | On page reload |
Sources: FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md, frontend/src/lib/stores/workflow-store.ts
Conclusion
The state management strategy effectively balances the need for high-performance UI components (via Zustand) with robust data synchronization and caching (via TanStack Query). By separating concerns into domain-specific stores and utilizing persistence middleware, the application provides a seamless user experience for complex tasks like visual workflow construction and CRM management. Sources: FRONTEND_IMPLEMENTATION_SUMMARY.md, DDD_IMPLEMENTATION_REPORT_SPEC_FRN_001.md