task_receipts/client/README.md

# React + TypeScript + Vite

This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.

Currently, two official plugins are available:

- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh

## Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:

```js
export default tseslint.config({
  extends: [
    // Remove ...tseslint.configs.recommended and replace with this
    ...tseslint.configs.recommendedTypeChecked,
    // Alternatively, use this for stricter rules
    ...tseslint.configs.strictTypeChecked,
    // Optionally, add this for stylistic rules
    ...tseslint.configs.stylisticTypeChecked,
  ],
  languageOptions: {
    // other options...
    parserOptions: {
      project: ['./tsconfig.node.json', './tsconfig.app.json'],
      tsconfigRootDir: import.meta.dirname,
    },
  },
})
```

You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:

```js
// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default tseslint.config({
  plugins: {
    // Add the react-x and react-dom plugins
    'react-x': reactX,
    'react-dom': reactDom,
  },
  rules: {
    // other rules...
    // Enable its recommended typescript rules
    ...reactX.configs['recommended-typescript'].rules,
    ...reactDom.configs.recommended.rules,
  },
})
```

# Task Receipts Client

A React application for managing task receipts with GraphQL API integration and Zustand state management.

## Architecture

### State Management with Zustand

The application uses Zustand for state management to optimize GraphQL API requests and improve performance:

#### Key Features:
- **Centralized State**: All task data is stored in a single Zustand store
- **Optimized Queries**: GraphQL queries are only made when data is not already available in the store
- **Efficient Updates**: Mutations update the store directly, reducing the need for refetching
- **Selective Rendering**: Components only re-render when their specific data changes

#### Store Structure:
```typescript
interface TaskState {
  // Data
  groups: GroupWithTasks[];
  recentTasks: TaskWithSteps[];
  frequentTasks: TaskWithSteps[];
  currentStep: StepWithNotes | null;

  // Loading states
  isLoadingGroups: boolean;
  isLoadingRecentTasks: boolean;
  isLoadingFrequentTasks: boolean;
  isLoadingStep: boolean;

  // Selection state
  selectedGroup: GroupWithTasks | undefined;
  selectedTask: TaskWithSteps | undefined;
  selectedStep: StepWithNotes | undefined;

  // Actions and helper methods...
}
```

#### Hooks:

1. **`useTaskDataOptimized`**: Main hook that manages GraphQL queries and store updates
2. **`useTaskSelector`**: Collection of selector hooks for efficient data access
3. **`useTaskStore`**: Direct access to the Zustand store

#### Performance Optimizations:

- **Skip Queries**: Queries are skipped if data already exists in the store
- **Cache-First Policy**: Apollo Client uses cache-first for queries
- **Selective Updates**: Only relevant parts of the store are updated
- **Efficient Selectors**: Components subscribe only to the data they need

### GraphQL Integration

The application uses Apollo Client for GraphQL operations with optimized caching policies:

- **Cache-First**: Queries prioritize cached data
- **Cache-and-Network**: Watch queries update from cache first, then network
- **Optimistic Updates**: Mutations update the store immediately

### Component Structure

- **App.tsx**: Main application component using the optimized hook
- **Layouts**: Desktop and mobile layouts for different screen sizes
- **Components**: Reusable UI components
- **Hooks**: Custom hooks for data management and device detection

## Development

### Prerequisites
- Node.js 18+
- npm or yarn

### Installation
```bash
npm install
```

### Development Server
```bash
npm run dev
```

### Build
```bash
npm run build
```

## State Management Flow

1. **Initial Load**:
   - `useTaskDataOptimized` checks if data exists in store
   - If not, makes GraphQL queries to fetch data
   - Updates store with fetched data

2. **User Interactions**:
   - Selection changes update store directly
   - Mutations update store optimistically
   - Components re-render only when their data changes

3. **Data Persistence**:
   - Store maintains data across component unmounts
   - Queries are skipped if data is already available
   - Cache policies ensure efficient data retrieval

## Benefits

- **Reduced API Calls**: Data is fetched once and reused
- **Better Performance**: Components only re-render when necessary
- **Improved UX**: Faster navigation and interactions
- **Maintainable Code**: Centralized state management
- **Type Safety**: Full TypeScript support with proper typing