veza/apps/web/src/docs/STATE_DEBUGGING.md

# State Debugging Guide

## FE-STATE-007: Add state debugging tools

This document outlines how to use Redux DevTools for debugging Zustand stores in the Veza frontend application.

## Overview

All Zustand stores in the application are configured with Redux DevTools middleware, which allows you to:

- Inspect state changes in real-time
- Time-travel through state history
- Export/import state snapshots
- Monitor action dispatches and their effects

## Setup

Redux DevTools is automatically enabled for all stores in development mode. The middleware is configured with:

- Store names for easy identification in DevTools
- Development-only activation (disabled in production)

## Stores Available for Debugging

The following stores are configured with DevTools:

1. **AuthStore** (`apps/web/src/features/auth/store/authStore.ts`)
   - Manages user authentication state
   - Tracks login/logout actions
   - Monitors user profile updates
   - **Note**: Contains `user` field (domain data - will migrate to React Query per Action 4.1.1.x)

2. **UIStore** (`apps/web/src/stores/ui.ts`)
   - Manages UI preferences (theme, language, sidebar)
   - Tracks notification state
   - Monitors UI state changes
   - **Category**: UI State (appropriate for Zustand)

3. **LibraryStore** (`apps/web/src/stores/library.ts`)
   - Manages library items and favorites
   - Tracks filter changes
   - Monitors item uploads and deletions
   - **Note**: Contains domain data (will migrate to React Query per Epic 4.1)

4. **ChatStore** (`apps/web/src/features/chat/store/chatStore.ts`) - Action 4.5.1.5: Moved from stores/chat.ts
   - Manages chat conversations and messages
   - Tracks WebSocket connection state
   - Monitors message operations
   - **Note**: ⚠️ **DUPLICATE** - Also exists at `features/chat/store/chatStore.ts` (needs consolidation per Action 4.5.1.5)

5. **CartStore** (`apps/web/src/stores/cartStore.ts`)
   - Manages shopping cart items
   - Tracks cart operations (add, remove, update quantity)
   - **Category**: UI State (client-side cart before checkout)

6. **PlayerStore** (`apps/web/src/features/player/store/playerStore.ts`)
   - Manages audio player state (current track, playback state, queue)
   - Tracks player controls and settings
   - **Category**: UI State (audio player state)

## Using Redux DevTools

### Installation

1. Install the [Redux DevTools Extension](https://github.com/reduxjs/redux-devtools-extension) for your browser:
   - [Chrome/Edge](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd)
   - [Firefox](https://addons.mozilla.org/en-US/firefox/addon/reduxdevtools/)

### Usage

1. **Open DevTools**: Press `F12` or right-click → Inspect
2. **Navigate to Redux Tab**: Click on the "Redux" tab in DevTools
3. **Select Store**: Use the dropdown to select which store to inspect (AuthStore, UIStore, LibraryStore, ChatStore, CartStore, PlayerStore)
4. **Inspect State**: View the current state tree
5. **Time Travel**: Use the slider or buttons to navigate through state history
6. **Action Details**: Click on any action to see its payload and resulting state changes

### Features

#### State Inspection

- View the complete state tree
- Search for specific state properties
- Expand/collapse nested objects

#### Action Monitoring

- See all dispatched actions in chronological order
- View action payloads
- See state diffs for each action

#### Time Travel Debugging

- Jump to any previous state
- Replay actions from a specific point
- Export state snapshots for sharing

#### State Export/Import

- Export current state as JSON
- Import state to restore a previous state
- Useful for reproducing bugs

## Example Workflow

### Debugging a State Issue

1. **Reproduce the Issue**: Perform the action that causes the problem
2. **Inspect Actions**: Look at the Redux DevTools action log to see what actions were dispatched
3. **Check State Changes**: Review the state diff to see what changed
4. **Time Travel**: Go back to before the issue occurred
5. **Export State**: Export the problematic state for further analysis

### Testing State Changes

1. **Record Actions**: Perform a series of actions
2. **Export State**: Export the final state
3. **Reset**: Clear the store or reload the page
4. **Import State**: Import the exported state to restore it
5. **Verify**: Confirm the state is restored correctly

## Best Practices

1. **Use Descriptive Store Names**: Store names in DevTools help identify which store you're debugging
2. **Monitor in Development**: DevTools is only enabled in development mode for performance
3. **Export Problematic States**: When reporting bugs, export the state snapshot to help developers reproduce the issue
4. **Time Travel Carefully**: Be aware that time-traveling can cause side effects (e.g., API calls won't be replayed)

## Troubleshooting

### DevTools Not Showing Stores

- Ensure you're in development mode (`import.meta.env.DEV === true`)
- Check that the Redux DevTools extension is installed and enabled
- Refresh the page after installing the extension

### Stores Not Appearing in Dropdown

- Verify that the stores are being used in the application
- Check that the `devtools` middleware is properly configured
- Ensure store names are unique and descriptive

### Performance Issues

- DevTools can impact performance in development
- Disable DevTools for specific stores if needed by setting `enabled: false`
- Use the "Skip" feature in DevTools to ignore certain actions

## Advanced Configuration

### Custom DevTools Configuration

You can customize DevTools behavior per store:

```typescript
devtools(
  // ... store implementation
  {
    name: 'MyStore',
    enabled: import.meta.env.DEV,
    // Additional options:
    // trace: true, // Enable stack traces
    // traceLimit: 25, // Limit stack trace depth
  },
);
```

### Disabling DevTools for Specific Stores

If you need to disable DevTools for a specific store:

```typescript
devtools(
  // ... store implementation
  {
    name: 'MyStore',
    enabled: false, // Disable DevTools
  },
);
```

## Related Documentation

- [Zustand DevTools Middleware](https://github.com/pmndrs/zustand#devtools)
- [Redux DevTools Extension](https://github.com/reduxjs/redux-devtools-extension)
- [Zustand Documentation](https://zustand-demo.pmnd.rs/)