ADR-005: Frontend State Management and Server Cache Strategy

Date: 2025-12-12 Implementation Date: 2026-01-08

Status: Accepted and Implemented (Phases 1 & 2 complete)

Context

The frontend currently uses React's built-in hooks (useState, useEffect, useContext) for state management, as seen in useAuth.tsx. While effective for simple cases, this manual approach becomes complex and error-prone when fetching, caching, and synchronizing data with the server. It often leads to custom logic for loading states, errors, re-fetching, and optimistic updates.

Decision

We will adopt a dedicated library for managing server state, such as TanStack Query (formerly React Query) or SWR, for all server-side data fetching on the client. This will abstract away the complexities of caching, background re-validation, and request deduplication.

Consequences

Positive: Leads to a more performant, predictable, and simpler frontend codebase. Standardizes how the client-side communicates with the server and handles loading/error states. Improves user experience through intelligent caching. Negative: Introduces a new frontend dependency. Requires a learning curve for developers unfamiliar with the library. Requires refactoring of existing data-fetching logic.

Implementation Status

Phase 1: Infrastructure & Core Queries (✅ Complete - 2026-01-08)

Files Created:

src/config/queryClient.ts - Global QueryClient configuration
src/hooks/queries/useFlyersQuery.ts - Flyers data query
src/hooks/queries/useWatchedItemsQuery.ts - Watched items query
src/hooks/queries/useShoppingListsQuery.ts - Shopping lists query

Files Modified:

src/providers/AppProviders.tsx - Added QueryClientProvider wrapper
src/providers/FlyersProvider.tsx - Refactored to use TanStack Query
src/providers/UserDataProvider.tsx - Refactored to use TanStack Query
src/services/apiClient.ts - Added pagination params to fetchFlyers

Benefits Achieved:

✅ Removed ~150 lines of custom state management code
✅ Automatic caching of server data
✅ Background refetching for stale data
✅ React Query Devtools available in development
✅ Automatic data invalidation on user logout
✅ Better error handling and loading states

Phase 2: Remaining Queries (✅ Complete - 2026-01-08)

Files Created:

src/hooks/queries/useMasterItemsQuery.ts - Master grocery items query
src/hooks/queries/useFlyerItemsQuery.ts - Flyer items query

Files Modified:

src/providers/MasterItemsProvider.tsx - Refactored to use TanStack Query
src/hooks/useFlyerItems.ts - Refactored to use TanStack Query

Benefits Achieved:

✅ Removed additional ~50 lines of custom state management code
✅ Per-flyer item caching (items cached separately for each flyer)
✅ Longer cache times for infrequently changing data (master items)
✅ Automatic query disabling when dependencies are not met

Phase 3: Mutations (⏳ Pending)

Add/remove watched items
Shopping list CRUD operations
Optimistic updates
Cache invalidation strategies

Phase 4: Cleanup (⏳ Pending)

Remove deprecated custom hooks
Remove stub implementations
Update all dependent components

Implementation Guide

See plans/adr-0005-implementation-plan.md for detailed implementation steps.

3.8 KiB Raw Blame History