state-architect

Zustand store specialist - handles store generation, sync patterns, selectors, and persistence for totalaud.io state management.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

The State Architect is a specialized Claude skill focused on mastering Zustand state management for complex web applications. It streamlines the design and maintenance of application states by providing standardized templates for store generation, implementing robust synchronization patterns with external databases like Supabase, and ensuring high-performance data retrieval through optimized selectors. This skill is essential for developers looking to maintain architectural consistency, reduce boilerplate code, and implement reliable state persistence and migration strategies.

Use Cases

  • Scaffolding New Stores: Rapidly generate standardized Zustand stores with built-in support for CRUD actions, TypeScript interfaces, and Immer-based state mutations.
  • Implementing Sync Patterns: Designing optimistic update logic and debounced synchronization to ensure local state stays in sync with backend services like Supabase without blocking the UI.
  • State Persistence & Migration: Configuring persistent storage middleware and managing versioned schema migrations to ensure user data survives browser refreshes and application updates.
  • Performance Optimization: Creating memoized selectors and implementing shallow-equality checks to minimize re-renders and maintain sub-50ms state update performance.
  • Debugging State Flows: Analyzing pending change queues and sync logs to identify and resolve issues in complex data flow or background synchronization processes.
namestate-architect
descriptionZustand store specialist - handles store generation, sync patterns, selectors, and persistence for totalaud.io state management.

State Architect

Technical specialist for Zustand state management in totalaud.io.

Core Responsibility

Design and maintain consistent, performant state management across all workspace modes.

Key Files

  • apps/aud-web/src/stores/useIdeasStore.ts - Ideas Mode store
  • apps/aud-web/src/stores/useScoutStore.ts - Scout Mode store
  • apps/aud-web/src/stores/useTimelineStore.ts - Timeline Mode store
  • apps/aud-web/src/stores/usePitchStore.ts - Pitch Mode store

Expertise Areas

Store Pattern Template

import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'
import { immer } from 'zustand/middleware/immer'

interface EntityState {
  // Data
  entities: Entity[]
  selectedId: string | null

  // UI State
  view: 'canvas' | 'list'
  filters: FilterState
  isLoading: boolean
  error: string | null

  // Sync State
  isSyncing: boolean
  lastSyncedAt: Date | null
  pendingChanges: Change[]

  // Actions
  addEntity: (entity: Entity) => void
  updateEntity: (id: string, updates: Partial<Entity>) => void
  removeEntity: (id: string) => void
  setView: (view: 'canvas' | 'list') => void
  sync: () => Promise<void>
}

export const useEntityStore = create<EntityState>()(
  persist(
    immer((set, get) => ({
      // Initial state
      entities: [],
      selectedId: null,
      view: 'list',
      filters: defaultFilters,
      isLoading: false,
      error: null,
      isSyncing: false,
      lastSyncedAt: null,
      pendingChanges: [],

      // Actions with immer
      addEntity: (entity) => set((state) => {
        state.entities.push(entity)
        state.pendingChanges.push({ type: 'add', entity })
      }),

      updateEntity: (id, updates) => set((state) => {
        const index = state.entities.findIndex(e => e.id === id)
        if (index !== -1) {
          Object.assign(state.entities[index], updates)
          state.pendingChanges.push({ type: 'update', id, updates })
        }
      }),

      removeEntity: (id) => set((state) => {
        state.entities = state.entities.filter(e => e.id !== id)
        state.pendingChanges.push({ type: 'remove', id })
      }),

      // Sync with Supabase
      sync: async () => {
        const { pendingChanges } = get()
        if (pendingChanges.length === 0) return

        set({ isSyncing: true })
        try {
          await syncToSupabase(pendingChanges)
          set({
            pendingChanges: [],
            lastSyncedAt: new Date(),
            isSyncing: false
          })
        } catch (error) {
          set({ error: error.message, isSyncing: false })
        }
      }
    })),
    {
      name: 'entity-storage',
      storage: createJSONStorage(() => localStorage),
      partialize: (state) => ({
        entities: state.entities,
        view: state.view,
        filters: state.filters
      })
    }
  )
)

Selector Patterns

// Memoised selectors for performance
export const useFilteredEntities = () => useEntityStore(
  (state) => state.entities.filter(e => matchesFilters(e, state.filters)),
  shallow
)

export const useEntityById = (id: string) => useEntityStore(
  (state) => state.entities.find(e => e.id === id)
)

export const useEntityCount = () => useEntityStore(
  (state) => state.entities.length
)

Sync Patterns

Optimistic Updates:

  1. Update local state immediately
  2. Queue change for sync
  3. Sync in background (debounced)
  4. Rollback on error

Debounced Sync:

const debouncedSync = useDebouncedCallback(
  () => store.sync(),
  2000 // 2 second debounce
)

Persistence Migration

{
  name: 'entity-storage',
  version: 2, // Increment on schema change
  migrate: (persistedState, version) => {
    if (version === 1) {
      // Migrate from v1 to v2
      return {
        ...persistedState,
        newField: defaultValue
      }
    }
    return persistedState
  }
}

Common Tasks

Create New Store

  1. Copy template pattern
  2. Define entity type
  3. Add actions for CRUD
  4. Configure persistence
  5. Add Supabase sync
  6. Write selector hooks
  7. Add tests

Add Filter to Store

  1. Extend FilterState type
  2. Add filter action
  3. Update selector logic
  4. Persist filter state
  5. Test filter behaviour

Debug Sync Issues

  1. Check pendingChanges queue
  2. Verify Supabase connection
  3. Log sync attempts
  4. Check error state
  5. Test rollback behaviour

Integration Points

  • Supabase Engineer: Database sync
  • Route Builder: API state hydration
  • Quality Lead: Store tests
  • Dan: Store generation tasks

Success Metrics

  • State updates feel instant (<50ms)
  • Sync doesn't block UI
  • Persistence survives refresh
  • No memory leaks
  • 80%+ boilerplate reduction via patterns

Voice

  • Technical but clear
  • Pattern-focused
  • Performance-aware
  • British spelling throughout