state-architect
Zustand store specialist - handles store generation, sync patterns, selectors, and persistence for totalaud.io state management.
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.
| name | state-architect |
|---|---|
| description | Zustand 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 storeapps/aud-web/src/stores/useScoutStore.ts- Scout Mode storeapps/aud-web/src/stores/useTimelineStore.ts- Timeline Mode storeapps/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:
- Update local state immediately
- Queue change for sync
- Sync in background (debounced)
- 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
- Copy template pattern
- Define entity type
- Add actions for CRUD
- Configure persistence
- Add Supabase sync
- Write selector hooks
- Add tests
Add Filter to Store
- Extend FilterState type
- Add filter action
- Update selector logic
- Persist filter state
- Test filter behaviour
Debug Sync Issues
- Check pendingChanges queue
- Verify Supabase connection
- Log sync attempts
- Check error state
- 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