torbo/flyer-crawler.projectium.com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
flyer-crawler.projectium.com/plans/adr-0005-master-migration-status.md
Torben Sorensen 2913c7aa09
Some checks failed
Deploy to Test Environment / deploy-to-test (push) Failing after 1m1s
Details
tanstack
2026-01-10 03:20:40 -08:00

281 lines
17 KiB
Markdown
Raw Permalink Blame History

# 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](../src/hooks/queries/useFlyersQuery.ts) | `['flyers', { limit, offset }]` | ✅ Done | 1 |
| useFlyerItemsQuery | [src/hooks/queries/useFlyerItemsQuery.ts](../src/hooks/queries/useFlyerItemsQuery.ts) | `['flyer-items', flyerId]` | ✅ Done | 2 |
| useMasterItemsQuery | [src/hooks/queries/useMasterItemsQuery.ts](../src/hooks/queries/useMasterItemsQuery.ts) | `['master-items']` | ✅ Done | 2 |
| useWatchedItemsQuery | [src/hooks/queries/useWatchedItemsQuery.ts](../src/hooks/queries/useWatchedItemsQuery.ts) | `['watched-items']` | ✅ Done | 1 |
| useShoppingListsQuery | [src/hooks/queries/useShoppingListsQuery.ts](../src/hooks/queries/useShoppingListsQuery.ts) | `['shopping-lists']` | ✅ Done | 1 |
| useUserAddressQuery | [src/hooks/queries/useUserAddressQuery.ts](../src/hooks/queries/useUserAddressQuery.ts) | `['user-address', addressId]` | ✅ Done | 7 |
| useAuthProfileQuery | [src/hooks/queries/useAuthProfileQuery.ts](../src/hooks/queries/useAuthProfileQuery.ts) | `['auth-profile']` | ✅ Done | 7 |
### Mutation Hooks (8)
| Hook | File | Invalidates | Status | Phase |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------- | ------- | ----- |
| useAddWatchedItemMutation | [src/hooks/mutations/useAddWatchedItemMutation.ts](../src/hooks/mutations/useAddWatchedItemMutation.ts) | `['watched-items']` | ✅ Done | 3 |
| useRemoveWatchedItemMutation | [src/hooks/mutations/useRemoveWatchedItemMutation.ts](../src/hooks/mutations/useRemoveWatchedItemMutation.ts) | `['watched-items']` | ✅ Done | 3 |
| useCreateShoppingListMutation | [src/hooks/mutations/useCreateShoppingListMutation.ts](../src/hooks/mutations/useCreateShoppingListMutation.ts) | `['shopping-lists']` | ✅ Done | 3 |
| useDeleteShoppingListMutation | [src/hooks/mutations/useDeleteShoppingListMutation.ts](../src/hooks/mutations/useDeleteShoppingListMutation.ts) | `['shopping-lists']` | ✅ Done | 3 |
| useAddShoppingListItemMutation | [src/hooks/mutations/useAddShoppingListItemMutation.ts](../src/hooks/mutations/useAddShoppingListItemMutation.ts) | `['shopping-lists']` | ✅ Done | 3 |
| useUpdateShoppingListItemMutation | [src/hooks/mutations/useUpdateShoppingListItemMutation.ts](../src/hooks/mutations/useUpdateShoppingListItemMutation.ts) | `['shopping-lists']` | ✅ Done | 3 |
| useRemoveShoppingListItemMutation | [src/hooks/mutations/useRemoveShoppingListItemMutation.ts](../src/hooks/mutations/useRemoveShoppingListItemMutation.ts) | `['shopping-lists']` | ✅ Done | 3 |
| useGeocodeMutation | [src/hooks/mutations/useGeocodeMutation.ts](../src/hooks/mutations/useGeocodeMutation.ts) | N/A | ✅ Done | 7 |
### Providers Migrated (5)
| Provider | Uses | Status |
| ------------------------------------------------------------------- | -------------------------------------------- | ------- |
| [AppProviders.tsx](../src/providers/AppProviders.tsx) | QueryClientProvider wrapper | ✅ Done |
| [FlyersProvider.tsx](../src/providers/FlyersProvider.tsx) | useFlyersQuery | ✅ Done |
| [MasterItemsProvider.tsx](../src/providers/MasterItemsProvider.tsx) | useMasterItemsQuery | ✅ Done |
| [UserDataProvider.tsx](../src/providers/UserDataProvider.tsx) | useWatchedItemsQuery + useShoppingListsQuery | ✅ Done |
| [AuthProvider.tsx](../src/providers/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](../src/hooks/queries/useActivityLogQuery.ts) | `['activity-log', { limit, offset }]` | ✅ Done | 5 |
| useApplicationStatsQuery | [src/hooks/queries/useApplicationStatsQuery.ts](../src/hooks/queries/useApplicationStatsQuery.ts) | `['application-stats']` | ✅ Done | 5 |
| useSuggestedCorrectionsQuery | [src/hooks/queries/useSuggestedCorrectionsQuery.ts](../src/hooks/queries/useSuggestedCorrectionsQuery.ts) | `['suggested-corrections']` | ✅ Done | 5 |
| useCategoriesQuery | [src/hooks/queries/useCategoriesQuery.ts](../src/hooks/queries/useCategoriesQuery.ts) | `['categories']` | ✅ Done | 5 |
### Admin Components Migrated (3)
| Component | Uses | Status |
| ------------------------------------------------------------- | --------------------------------------------------------------------- | ------- |
| [ActivityLog.tsx](../src/pages/admin/ActivityLog.tsx) | useActivityLogQuery | ✅ Done |
| [AdminStatsPage.tsx](../src/pages/admin/AdminStatsPage.tsx) | useApplicationStatsQuery | ✅ Done |
| [CorrectionsPage.tsx](../src/pages/admin/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](../src/hooks/queries/useBestSalePricesQuery.ts) | `['best-sale-prices']` | ✅ Done | 6 |
| useFlyerItemsForFlyersQuery | [src/hooks/queries/useFlyerItemsForFlyersQuery.ts](../src/hooks/queries/useFlyerItemsForFlyersQuery.ts) | `['flyer-items-batch', flyerIds]` | ✅ Done | 6 |
| useFlyerItemCountQuery | [src/hooks/queries/useFlyerItemCountQuery.ts](../src/hooks/queries/useFlyerItemCountQuery.ts) | `['flyer-item-count', flyerIds]` | ✅ Done | 6 |
### Analytics Components/Hooks Migrated (2)
| Component/Hook | Uses | Status |
| ----------------------------------------------------- | --------------------------------------------------- | ------- |
| [MyDealsPage.tsx](../src/pages/MyDealsPage.tsx) | useBestSalePricesQuery | ✅ Done |
| [useActiveDeals.tsx](../src/hooks/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](../src/pages/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](../src/hooks/queries/useUserAddressQuery.ts) | Fetch user address by ID |
| useAuthProfileQuery | [src/hooks/queries/useAuthProfileQuery.ts](../src/hooks/queries/useAuthProfileQuery.ts) | Fetch authenticated user profile |
| useGeocodeMutation | [src/hooks/mutations/useGeocodeMutation.ts](../src/hooks/mutations/useGeocodeMutation.ts) | Geocode address strings |
### Files Modified (Phase 7)
| File | Change |
| --------------------------------------------------------- | ---------------------------------------------------------- |
| [useProfileAddress.ts](../src/hooks/useProfileAddress.ts) | Refactored to use useUserAddressQuery + useGeocodeMutation |
| [AuthProvider.tsx](../src/providers/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)
- [x] Refactor useWatchedItems to use mutation hooks
- [x] Refactor useShoppingLists to use mutation hooks
- [x] Remove deprecated setters from context
### ✅ Phase 5: Admin Features (Complete)
- [x] Create useActivityLogQuery
- [x] Create useApplicationStatsQuery
- [x] Create useSuggestedCorrectionsQuery
- [x] Create useCategoriesQuery
- [x] Migrate ActivityLog.tsx
- [x] Migrate AdminStatsPage.tsx
- [x] Migrate CorrectionsPage.tsx
### ✅ Phase 6: Analytics Features (Complete - 2026-01-10)
- [x] Create useBestSalePricesQuery
- [x] Create useFlyerItemsForFlyersQuery
- [x] Create useFlyerItemCountQuery
- [x] Migrate MyDealsPage.tsx
- [x] Refactor useActiveDeals to use TanStack Query
### ✅ Phase 7: Cleanup (Complete - 2026-01-10)
- [x] Create useUserAddressQuery
- [x] Create useAuthProfileQuery
- [x] Create useGeocodeMutation
- [x] Migrate useProfileAddress from useApi to TanStack Query
- [x] Migrate AuthProvider from useApi to TanStack Query
- [x] Remove useApi hook
- [x] Remove useApiOnMount hook
### ✅ Phase 8: Additional Component Migration (Complete - 2026-01-10)
- [x] Create useUserProfileDataQuery (combined profile + achievements)
- [x] Create useLeaderboardQuery (public leaderboard data)
- [x] Create usePriceHistoryQuery (historical price data for watched items)
- [x] Refactor useUserProfileData to use TanStack Query
- [x] Refactor Leaderboard.tsx to use useLeaderboardQuery
- [x] 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:
```typescript
// 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](../docs/adr/0005-frontend-state-management-and-server-cache-strategy.md)
- [Phase 1 Implementation Plan](./adr-0005-implementation-plan.md)
- [Phase 2 Summary](./adr-0005-phase-2-summary.md)
- [Phase 3 Summary](./adr-0005-phase-3-summary.md)
- [This Document](./adr-0005-master-migration-status.md)
Reference in New Issue View Git Blame Copy Permalink