mission-control/docs/tanstack-query-zustand-migration-plan.md

# TanStack Query + Zustand Migration Plan

Last updated: February 25, 2026

## Goal

Improve page-load performance and consistency across both projects by introducing a clear data-layer split:

- TanStack Query for all server state (fetching, cache, refetch, invalidation)
- Zustand for UI/client state only (selection, view mode, dialogs, preferences)

Projects in scope:

- `mission-control` (`/Users/mattbruce/Documents/Projects/OpenClaw/Web/mission-control`)
- `gantt-board` (`/Users/mattbruce/Documents/Projects/OpenClaw/Web/gantt-board`)

Both apps use the same Supabase backend.

## Locked Decisions

- Rollout strategy: incremental by route
- Mutation strategy: optimistic updates + rollback on error
- Freshness strategy: invalidate/refetch only (no Supabase Realtime in this phase)
- `mission-control` scope for this phase: client data paths only
  - activity, documents, quick search, task due-dates widget, auth session checks
  - keep server-rendered dashboard/task/project overview pages unchanged
- `gantt-board` scope for this phase: migrate board/task/project/sprint client data flows off store-driven sync

## Current Problems To Fix

### `gantt-board`

- `src/stores/useTaskStore.ts` mixes server data + UI state + network side effects
- frequent full `syncFromServer()` calls
- repetitive `fetch("/api/auth/users")` and `fetch("/api/auth/session")` across routes/components
- mutation flow often does write then full refetch

### `mission-control`

- isolated client hooks perform uncached fetches
  - `hooks/use-activity-feed.ts`
  - `hooks/useDocuments.ts`
  - `components/calendar/TaskCalendarIntegration.tsx`
  - `components/layout/quick-search.tsx`
- duplicated activity fetch work across multiple widgets/components
- documents refresh currently uses full page reload

## Target Architecture

1. Per-repo query layer

- `lib/query/client.ts` (or `src/lib/query/client.ts`)
- `lib/query/keys.ts`
- `lib/query/fetcher.ts`
- domain hooks in `lib/query/hooks/*`

2. Global defaults

- `gcTime`: 10 minutes
- `retry`: 1 for idempotent GET queries
- `retry`: 0 for auth/session checks and mutation-like flows
- `refetchOnReconnect`: `true`
- `refetchOnWindowFocus`: `true` for board/activity/session data, `false` for quick-search query

3. Stale-time defaults

- session: 30s
- tasks snapshot (active-sprint): 15s
- tasks snapshot (all): 60s
- task detail snapshot: 30s
- users list: 5m
- projects/sprints lists: 60s
- documents list: 60s
- quick search: 20s
- due-dates widget: 60s

4. Zustand boundary

- retain UI state only
- remove network fetch/sync logic from stores
- persist only stable UI preferences and selections

## Query Key Contract

Use stable keys in both repos:

```ts
["auth", "session"]
["users", "directory"]      // mission-control: /api/users/directory
["users", "auth-list"]      // gantt-board: /api/auth/users
["tasks", "snapshot", { scope: "active-sprint" | "all", include?: "detail", taskId?: string }]
["projects", "list"]
["sprints", "list", { status?: "planning" | "active" | "completed" }]
["sprints", "current", { projectId?: string, includeCompletedFallback?: boolean }]
["documents", "list"]
["tasks", "due-dates", { limit: number }]
["search", { q: string }]
["activity", { limit: number, projectId?: string, filterType?: string }]
```

## Planned Hook Interfaces

- `useSessionQuery()`
- `useBoardSnapshotQuery(params)` (`gantt-board`)
- `useUpsertTaskMutation()`
- `useDeleteTaskMutation()`
- `useProjectMutations()`
- `useSprintMutations()`
- `useActivityQuery(params)` (`mission-control`)
- `useDocumentsQuery()`
- `useTasksDueDatesQuery(limit)`
- `useQuickSearchQuery(q)`

## Phased Implementation

## Phase 1: Shared Infrastructure

Both repos:

1. Ensure root Query provider with shared query-client defaults
2. Add typed fetcher helper with abort/error normalization
3. Add query key factory and domain API wrappers
4. Add cache patch + invalidation utility helpers

## Phase 2: `gantt-board` Main Board Route

1. Replace `syncFromServer`/auth `useEffect` flow in `src/app/page.tsx` with queries
2. Load active-sprint snapshot first; fetch full snapshot when entering backlog/search
3. Replace direct users fetch with shared users query
4. Move task/project/sprint writes to TanStack mutation hooks
5. Apply optimistic update + rollback + targeted invalidation

## Phase 3: `gantt-board` Secondary Routes

1. Task detail route -> detail query (`include=detail`, `taskId`) + mutation hooks
2. Projects list and project detail routes -> query-based data + no manual `syncFromServer`
3. Sprint archive route -> query-based sprints/tasks and derived stats
4. Search/backlog user lookups -> shared cached users query
5. Reduce `useTaskStore` to UI-only store with compatibility layer during migration

## Phase 4: `mission-control` Client Data Paths

1. Add Query provider in app layout
2. Replace `use-activity-feed` internal polling/state with `useQuery` + `refetchInterval: 30000`
3. Replace `useDocuments` mount fetch + reload refresh with query + invalidation/refetch
4. Replace due-dates widget `fetch` with query hook
5. Replace quick-search effect `fetch` with debounced query (`enabled: q.length >= 2`)
6. Replace login session precheck `useEffect` with session query
7. Keep server-rendered dashboard/task/project overviews unchanged for this phase

## Phase 5: Cleanup

1. Remove dead network/sync paths from Zustand stores
2. Remove hardcoded/default mock payloads in stores where no longer used
3. Remove unused `swr` dependency in `gantt-board` if still unused
4. Normalize loading/error/empty states from query status
5. Ensure no full-page reload is used for data refresh paths

## Mutation Invalidation Matrix

- Task create/update/delete/comment/attachment:
  - invalidate task snapshot keys (all relevant scopes), due-dates keys, and activity keys if impacted
- Project mutations:
  - invalidate projects + task snapshots + sprint current/list keys
- Sprint mutations:
  - invalidate sprint list/current + task snapshot keys
- Auth login/logout/account changes:
  - invalidate session + users keys

## Testing Plan

## Automated

1. Query key stability tests for parameterized keys
2. Optimistic mutation tests:
   - success keeps optimistic value and reconciles
   - error rolls back
3. Hook integration tests:
   - active-sprint initial load
   - full-scope lazy load when switching view
   - deduped users lookup fetches across mounts
4. Keep existing `gantt-board` API/CLI contract tests passing

## Manual Acceptance

1. `gantt-board` initial load should issue one session query, one active-sprint query, one users query
2. Backlog/search switch should not refetch full snapshot on every render
3. Drag/drop should update instantly and rollback correctly on error
4. Task detail should load detail payload without forcing global full sync
5. `mission-control` activity widgets should share cached activity data instead of duplicate requests
6. Documents refresh should no longer reload the page
7. Quick search should debounce and reuse cache for repeat queries

## Performance Exit Criteria

1. Warm route visits should render from cache first with background refetch
2. Redundant network requests should drop materially on board/activity/document-heavy flows
3. No hard refresh required to see server-backed updates

## Migration Touchpoints (Primary)

`mission-control`:

- `app/layout.tsx`
- `hooks/use-activity-feed.ts`
- `hooks/useDocuments.ts`
- `components/layout/quick-search.tsx`
- `components/calendar/TaskCalendarIntegration.tsx`
- `app/login/page.tsx`

`gantt-board`:

- `src/components/QueryProvider.tsx`
- `src/stores/useTaskStore.ts`
- `src/app/page.tsx`
- `src/app/tasks/[taskId]/page.tsx`
- `src/app/projects/page.tsx`
- `src/app/projects/[id]/page.tsx`
- `src/app/sprints/archive/page.tsx`

## Notes For Future Chats

If a new chat needs to continue this effort, reference:

- this file path directly
- "TanStack Query + Zustand migration plan (Feb 25, 2026)"
- the locked decisions section above