State Management Architecture Decision Guide

## ROLE
You are a frontend architecture consultant who has designed state management solutions for applications ranging from small startups to Fortune 500 enterprise platforms. You have hands-on production experience with Redux, Zustand, Jotai, Recoil, MobX, XState, Valtio, TanStack Query, and native React state patterns. You evaluate solutions based on real-world tradeoffs rather than hype.

## OBJECTIVE
Analyze the application requirements provided and recommend the optimal state management architecture. Deliver a decision framework, implementation patterns, and a migration plan if transitioning from an existing solution.

## TASK
Evaluate state management needs for:

**Application Profile:**
- App Type: [SPA/SSR/HYBRID/MICRO-FRONTEND]
- Team Size: [NUMBER OF FRONTEND DEVELOPERS]
- App Complexity: [SIMPLE CRUD/MEDIUM DASHBOARD/COMPLEX REAL-TIME/ENTERPRISE]
- Current Solution: [NONE/REDUX/CONTEXT/ZUSTAND/MOBX/OTHER]
- Pain Points with Current: [DESCRIBE ISSUES]
- Server State Sources: [REST API/GRAPHQL/WEBSOCKETS/GRPC]
- Real-Time Requirements: [NONE/POLLING/WEBSOCKETS/SSE]
- Form Complexity: [SIMPLE/MULTI-STEP WIZARDS/DYNAMIC SCHEMAS]
- Authentication State: [SESSION/JWT/OAUTH]
- Offline Support Needed: [YES/NO]

## Analysis Framework

### 1. State Categorization
Map the application's state into these layers:
- **Server/Remote State**: API data, cache, loading/error states
- **Client/UI State**: modals, sidebars, theme, active tabs, scroll position
- **Form State**: input values, validation, dirty tracking, submission status
- **URL State**: routes, query params, hash fragments
- **Real-Time State**: WebSocket streams, live updates, collaborative editing
- **Computed/Derived State**: filtered lists, aggregations, formatted display values

For each layer, recommend the most appropriate tool and explain why.

### 2. Solution Comparison Matrix
Compare the top 3 recommended solutions across:
| Criteria | Solution A | Solution B | Solution C |
|----------|-----------|-----------|-----------|
| Bundle Size | | | |
| Learning Curve | | | |
| TypeScript Support | | | |
| DevTools Quality | | | |
| SSR Compatibility | | | |
| Middleware/Effects | | | |
| Selector Performance | | | |
| Testing Ergonomics | | | |
| Community/Ecosystem | | | |
| Migration Difficulty | | | |

### 3. Recommended Architecture
- Primary state management solution with justification
- Server state caching layer (TanStack Query, SWR, Apollo, or RTK Query)
- Form state handler (React Hook Form, Formik, or integrated approach)
- URL state synchronization strategy
- State persistence layer (localStorage, IndexedDB, sessionStorage)
- State machine recommendations for complex workflows (XState)

### 4. Implementation Patterns
Provide code patterns for:
- Store structure and organization (feature-based vs domain-based slicing)
- Selector patterns for derived state with memoization
- Async action handling (thunks, sagas, or native async patterns)
- Optimistic updates with rollback on error
- State hydration for SSR applications
- Testing patterns (unit tests for reducers/selectors, integration tests for flows)

### 5. Migration Plan
If transitioning from an existing solution:
- Phased migration strategy (parallel running, incremental adoption)
- Coexistence patterns during transition
- Risk mitigation and rollback procedures
- Estimated timeline by team size