flyer-crawler.projectium.com/plans/adr-0005-master-migration-status.md

ADR-0005 Master Migration Status

Last Updated: 2026-01-10

This document tracks the complete migration status of all data fetching patterns in the application to TanStack Query (React Query) as specified in ADR-0005.

Migration Overview

Category	Total	Migrated	Remaining	% Complete
User Features	7 queries + 8 mutations	15/15	0	✅ 100%
User Hooks	3 hooks	3/3	0	✅ 100%
Admin Features	4 queries + 3 components	7/7	0	✅ 100%
Analytics Features	3 queries + 2 components	5/5	0	✅ 100%
Legacy Hooks	4 items	4/4	0	✅ 100%
Phase 8 Queries	3 queries	3/3	0	✅ 100%
Phase 8 Components	3 components	3/3	0	✅ 100%
TOTAL	40 items	40/40	0	✅ 100%

---

✅ COMPLETED: User-Facing Features (Phase 1-3)

Query Hooks (7)

Hook	File	Query Key	Status	Phase
useFlyersQuery	src/hooks/queries/useFlyersQuery.ts	['flyers', { limit, offset }]	✅ Done	1
useFlyerItemsQuery	src/hooks/queries/useFlyerItemsQuery.ts	['flyer-items', flyerId]	✅ Done	2
useMasterItemsQuery	src/hooks/queries/useMasterItemsQuery.ts	['master-items']	✅ Done	2
useWatchedItemsQuery	src/hooks/queries/useWatchedItemsQuery.ts	['watched-items']	✅ Done	1
useShoppingListsQuery	src/hooks/queries/useShoppingListsQuery.ts	['shopping-lists']	✅ Done	1
useUserAddressQuery	src/hooks/queries/useUserAddressQuery.ts	['user-address', addressId]	✅ Done	7
useAuthProfileQuery	src/hooks/queries/useAuthProfileQuery.ts	['auth-profile']	✅ Done	7

Mutation Hooks (8)

Hook	File	Invalidates	Status	Phase
useAddWatchedItemMutation	src/hooks/mutations/useAddWatchedItemMutation.ts	['watched-items']	✅ Done	3
useRemoveWatchedItemMutation	src/hooks/mutations/useRemoveWatchedItemMutation.ts	['watched-items']	✅ Done	3
useCreateShoppingListMutation	src/hooks/mutations/useCreateShoppingListMutation.ts	['shopping-lists']	✅ Done	3
useDeleteShoppingListMutation	src/hooks/mutations/useDeleteShoppingListMutation.ts	['shopping-lists']	✅ Done	3
useAddShoppingListItemMutation	src/hooks/mutations/useAddShoppingListItemMutation.ts	['shopping-lists']	✅ Done	3
useUpdateShoppingListItemMutation	src/hooks/mutations/useUpdateShoppingListItemMutation.ts	['shopping-lists']	✅ Done	3
useRemoveShoppingListItemMutation	src/hooks/mutations/useRemoveShoppingListItemMutation.ts	['shopping-lists']	✅ Done	3
useGeocodeMutation	src/hooks/mutations/useGeocodeMutation.ts	N/A	✅ Done	7

Providers Migrated (5)

Provider	Uses	Status
AppProviders.tsx	QueryClientProvider wrapper	✅ Done
FlyersProvider.tsx	useFlyersQuery	✅ Done
MasterItemsProvider.tsx	useMasterItemsQuery	✅ Done
UserDataProvider.tsx	useWatchedItemsQuery + useShoppingListsQuery	✅ Done
AuthProvider.tsx	useAuthProfileQuery	✅ Done

---

✅ COMPLETED: Admin Features (Phase 5)

Admin Query Hooks (4)

Hook	File	Query Key	Status	Phase
useActivityLogQuery	src/hooks/queries/useActivityLogQuery.ts	['activity-log', { limit, offset }]	✅ Done	5
useApplicationStatsQuery	src/hooks/queries/useApplicationStatsQuery.ts	['application-stats']	✅ Done	5
useSuggestedCorrectionsQuery	src/hooks/queries/useSuggestedCorrectionsQuery.ts	['suggested-corrections']	✅ Done	5
useCategoriesQuery	src/hooks/queries/useCategoriesQuery.ts	['categories']	✅ Done	5

Admin Components Migrated (3)

Component	Uses	Status
ActivityLog.tsx	useActivityLogQuery	✅ Done
AdminStatsPage.tsx	useApplicationStatsQuery	✅ Done
CorrectionsPage.tsx	useSuggestedCorrectionsQuery, useMasterItemsQuery, useCategoriesQuery	✅ Done

---

✅ COMPLETED: Analytics Features (Phase 6)

Analytics Query Hooks (3)

Hook	File	Query Key	Status	Phase
useBestSalePricesQuery	src/hooks/queries/useBestSalePricesQuery.ts	['best-sale-prices']	✅ Done	6
useFlyerItemsForFlyersQuery	src/hooks/queries/useFlyerItemsForFlyersQuery.ts	['flyer-items-batch', flyerIds]	✅ Done	6
useFlyerItemCountQuery	src/hooks/queries/useFlyerItemCountQuery.ts	['flyer-item-count', flyerIds]	✅ Done	6

Analytics Components/Hooks Migrated (2)

Component/Hook	Uses	Status
MyDealsPage.tsx	useBestSalePricesQuery	✅ Done
useActiveDeals.tsx	useFlyerItemsForFlyersQuery, useFlyerItemCountQuery	✅ Done

Benefits Achieved:

• ✅ Removed useApi dependency from analytics features
• ✅ Automatic caching of deal data (2-5 minute stale times)
• ✅ Consistent error handling via TanStack Query
• ✅ Batch fetching for flyer items (single query for multiple flyers)

Low Priority - Voice Lab

Feature	Component	Current Pattern	Priority
Voice Lab	VoiceLabPage.tsx	Direct async/await	🟢 LOW

Notes:

• Event-driven API calls (not data fetching)
• Speech generation and voice sessions
• Mutation-like operations, not query-like
• Could create mutations but not critical for caching

---

✅ COMPLETED: Legacy Hook Cleanup (Phase 7)

Hooks Removed

Hook	Former File	Replaced By	Status
useApi	src/hooks/useApi.ts	TanStack Query hooks	✅ Removed
useApiOnMount	src/hooks/useApiOnMount.ts	TanStack Query hooks	✅ Removed

Additional Hooks Created (Phase 7)

Hook	File	Purpose
useUserAddressQuery	src/hooks/queries/useUserAddressQuery.ts	Fetch user address by ID
useAuthProfileQuery	src/hooks/queries/useAuthProfileQuery.ts	Fetch authenticated user profile
useGeocodeMutation	src/hooks/mutations/useGeocodeMutation.ts	Geocode address strings

Files Modified (Phase 7)

File	Change
useProfileAddress.ts	Refactored to use useUserAddressQuery + useGeocodeMutation
AuthProvider.tsx	Refactored to use useAuthProfileQuery

---

📊 MIGRATION PHASES

✅ Phase 1: Core Queries (Complete)

• Infrastructure setup (QueryClientProvider)
• Flyers, Watched Items, Shopping Lists queries
• Providers refactored

✅ Phase 2: Additional Queries (Complete)

• Master Items query
• Flyer Items query
• Per-resource caching strategies

✅ Phase 3: Mutations (Complete)

• All watched items mutations
• All shopping list mutations
• Automatic cache invalidation

✅ Phase 4: Hook Refactoring (Complete)

• Refactor useWatchedItems to use mutation hooks
• Refactor useShoppingLists to use mutation hooks
• Remove deprecated setters from context

✅ Phase 5: Admin Features (Complete)

• Create useActivityLogQuery
• Create useApplicationStatsQuery
• Create useSuggestedCorrectionsQuery
• Create useCategoriesQuery
• Migrate ActivityLog.tsx
• Migrate AdminStatsPage.tsx
• Migrate CorrectionsPage.tsx

✅ Phase 6: Analytics Features (Complete - 2026-01-10)

• Create useBestSalePricesQuery
• Create useFlyerItemsForFlyersQuery
• Create useFlyerItemCountQuery
• Migrate MyDealsPage.tsx
• Refactor useActiveDeals to use TanStack Query

✅ Phase 7: Cleanup (Complete - 2026-01-10)

• Create useUserAddressQuery
• Create useAuthProfileQuery
• Create useGeocodeMutation
• Migrate useProfileAddress from useApi to TanStack Query
• Migrate AuthProvider from useApi to TanStack Query
• Remove useApi hook
• Remove useApiOnMount hook

✅ Phase 8: Additional Component Migration (Complete - 2026-01-10)

• Create useUserProfileDataQuery (combined profile + achievements)
• Create useLeaderboardQuery (public leaderboard data)
• Create usePriceHistoryQuery (historical price data for watched items)
• Refactor useUserProfileData to use TanStack Query
• Refactor Leaderboard.tsx to use useLeaderboardQuery
• Refactor PriceHistoryChart.tsx to use usePriceHistoryQuery

---

🎉 MIGRATION COMPLETE

The TanStack Query migration is 100% complete. All data fetching in the application now uses TanStack Query for:

• Automatic caching - Server data is cached and shared across components
• Background refetching - Stale data is automatically refreshed
• Loading/error states - Consistent handling across the entire application
• Cache invalidation - Mutations automatically invalidate related queries
• DevTools - React Query DevTools available in development mode

---

📝 NOTES

Query Key Organization

Currently using literal strings for query keys. Consider creating a centralized query keys file:

// src/config/queryKeys.ts
export const queryKeys = {
  flyers: (limit: number, offset: number) => ['flyers', { limit, offset }] as const,
  flyerItems: (flyerId: number) => ['flyer-items', flyerId] as const,
  masterItems: () => ['master-items'] as const,
  watchedItems: () => ['watched-items'] as const,
  shoppingLists: () => ['shopping-lists'] as const,
  // Add admin keys
  activityLog: (limit: number, offset: number) => ['activity-log', { limit, offset }] as const,
  applicationStats: () => ['application-stats'] as const,
  suggestedCorrections: () => ['suggested-corrections'] as const,
  categories: () => ['categories'] as const,
  bestSalePrices: (itemIds: number[]) => ['best-sale-prices', itemIds] as const,
};

Cache Invalidation Strategy

Admin features may need different invalidation strategies:

• Activity log should refetch after mutations
• Stats should refetch after significant operations
• Corrections should refetch after approving/rejecting

Stale Time Recommendations

Data Type	Stale Time	Reasoning
Master Items	10 minutes	Rarely changes
Categories	10 minutes	Rarely changes
Flyers	2 minutes	Moderate changes
Flyer Items	5 minutes	Static once created
User Lists	1 minute	Frequent changes
Admin Stats	2 minutes	Moderate changes
Activity Log	30 seconds	Frequently updated
Corrections	1 minute	Moderate changes
Best Prices	2 minutes	Recalculated periodically
User Profile Data	5 minutes	User-specific, changes infrequently
Leaderboard	2 minutes	Public data, moderate updates
Price History	10 minutes	Historical data, rarely changes

---

📚 DOCUMENTATION

• ADR-0005 Main Document
• Phase 1 Implementation Plan
• Phase 2 Summary
• Phase 3 Summary
• This Document