State Management

The MATIH frontend employs a multi-layered state management strategy that matches the complexity of each domain. Zustand serves as the primary state library for cross-workbench coordination and user preferences, while individual workbenches may use Redux Toolkit for complex domain state. A custom lightweight store framework with middleware support provides an extensible foundation for specialized use cases.

State Management Layers

+--------------------------------------------------+
|  Server State (TanStack Query)                    |
|  - API responses, cache, refetch, pagination      |
+--------------------------------------------------+
|  Cross-Workbench State (Zustand)                  |
|  - Entity handoff, global filters, preferences    |
|  - BroadcastChannel sync, localStorage persist    |
+--------------------------------------------------+
|  Domain State (Zustand / Redux Toolkit)           |
|  - Dashboard state, DNN builder, pipeline editor  |
+--------------------------------------------------+
|  Component State (React useState/useReducer)      |
|  - Form inputs, UI toggles, local interactions    |
+--------------------------------------------------+

Cross-Workbench Store

The crossWorkbenchStore at frontend/shared/src/stores/crossWorkbenchStore.ts is the primary mechanism for sharing state between workbenches. It manages entity handoff, navigation requests, global filters, and catalog context.

State Shape

interface CrossWorkbenchState {
  // Entity handoff
  selectedEntity: SelectedEntity | null;
  entityHistory: SelectedEntity[];
 
  // Active catalog context
  activeCatalog: string | null;
  activeSchema: string | null;
  activeTable: string | null;
 
  // Cross-workbench navigation
  navigationRequest: NavigationRequest | null;
 
  // Shared filters
  globalFilters: Record<string, unknown>;
  globalTimeRange: GlobalTimeRange | null;
}

Entity Types

type EntityType =
  | 'table' | 'column' | 'pipeline' | 'model'
  | 'dashboard' | 'query' | 'experiment'
  | 'objectType' | 'dataset' | 'feature' | 'agent';
 
interface SelectedEntity {
  id: string;
  type: EntityType;
  name: string;
  fqn?: string;
  metadata: Record<string, unknown>;
  sourceWorkbench: string;
  selectedAt: string;
}

BroadcastChannel Synchronization

The store uses the browser BroadcastChannel API to synchronize state across browser tabs:

const BROADCAST_CHANNEL = 'matih-cross-workbench';
 
const broadcast = (partial: Partial<CrossWorkbenchState>) => {
  if (!isReceiving) {
    const ch = getBroadcastChannel();
    ch?.postMessage({ type: 'CROSS_WB_UPDATE', state: partial });
  }
};

Persistence Configuration

persist(storeCreator, {
  name: 'matih-cross-workbench',
  storage: createJSONStorage(() => localStorage),
  partialize: (state) => ({
    selectedEntity: state.selectedEntity,
    entityHistory: state.entityHistory,
    activeCatalog: state.activeCatalog,
    activeSchema: state.activeSchema,
    activeTable: state.activeTable,
    globalFilters: state.globalFilters,
    globalTimeRange: state.globalTimeRange,
    // navigationRequest intentionally excluded (ephemeral)
  }),
})

User Preferences Store

The preferencesStore manages appearance and accessibility settings with CSS variable application:

interface UserPreferences {
  theme: 'light' | 'dark' | 'system';
  fontSize: 'small' | 'medium' | 'large';
  density: 'compact' | 'comfortable' | 'spacious';
  reducedMotion: boolean;
  highContrast: boolean;
  focusIndicators: 'default' | 'enhanced';
  screenReaderOptimized: boolean;
  fontScale: number;  // 0.8 to 1.5
  commandPaletteRecentCommands: string[];
  sidebarCollapsed: boolean;
  notificationsEnabled: boolean;
  soundEnabled: boolean;
}

Custom Store Framework

Located at frontend/shared/src/state/:

Module	Purpose
`createStore.ts`	Generic store factory with middleware support
`atoms.ts`	Atomic state units for fine-grained reactivity
`history.ts`	Undo/redo state history middleware
`optimistic.ts`	Optimistic update patterns
`sync.ts`	Cross-tab and server synchronization
`query.ts`	Query state management

Workbench-Specific Stores

Workbench	Store	Key State
BI Workbench	`dashboard-store.ts`	Dashboards, widgets, filters, layout
ML Workbench	`dnnBuilderStore.ts`	Neural network layers, connections
Data Workbench	`layoutStore.ts`	Panel layout, active panels
Agentic Workbench	`store/index.ts`	Agent sessions, messages, workflows
Ops Workbench	`ops-store.ts`	Dashboard data, chat, alerts
Control Plane UI	`authStore.ts`	Auth state, tokens, user info
Data Plane UI	`authStore.ts` + `tenantStore.ts`	Auth, tenant context

Shared Component Library Authentication & API Client