React Query

React Query in MUZE

The frontend uses TanStack React Query v5 for all server state management. This replaces traditional Redux/Zustand patterns for API data.

Provider setup

// frontend/src/App.tsx
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: CACHE_TIERS.reference, // 15 min reference default (Phase 2.12)
      gcTime: CACHE_GC_TIME, // 30 min
      retry: 1,
      refetchOnWindowFocus: false,
      refetchOnMount: false, // cached-first render path
    },
  },
});

The provider wraps the app in App.tsx together with SessionProvider and the toast mount point.

Cache tiers (Phase 2.12)

Cached data is the default render path. Tier constants live in frontend/src/lib/cache-tiers.ts and are shared by pages, the warm-start prefetcher and the sidebar hover prefetch:

Tier	`staleTime`	`refetchOnMount`	Examples
Reference (global default)	15 min	`false`	clients, stores, regions, products, entitlement rule sets
Directory	5 min	`false`	employees, users/accounts, settings, audit trail
Operational	60 s	`true`	orders, approvals, status counts, stock, reports
Live	30 s	`true`	notifications / unread count
Session	5 min	`false`	`['me']`, `['role-permissions']`

Changes to reference/directory data are surfaced by the invalidation helpers in lib/query-invalidation.ts; operational queries opt back into refetchOnMount: true. Client-scoped admin and manager queries include activeClientId in the key and guard with enabled: !!activeClientId, so they fire only after the active client resolves. Client-sensitive queries do not use keepPreviousData; a client switch clears the old rows while fresh data loads. Prefetch keys for the login warm-start and the sidebar hover/focus prefetch come from the single lib/navigation-prefetch.ts registry, aligned exactly to the page keys. Sign-out cancels and clears the query cache before navigating to /login. Full policy: doc/architecture_and_workflow.md §10.6.

Query patterns

Fetching data

// Custom hook using React Query
export function useEmployees(storeId?: string) {
  return useQuery({
    queryKey: ['employees', storeId],
    queryFn: () => api.get(`/employees`, { params: { storeId } }),
    enabled: !!storeId,
  });
}

Creating data

export function useCreateEmployee() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: CreateEmployeeDto) =>
      api.post('/employees', data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['employees'] });
    },
  });
}

Updating data

export function useUpdateOrderStatus() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ id, status }: { id: string; status: OrderStatus }) =>
      api.patch(`/orders/${id}/status`, { status }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['orders'] });
    },
  });
}

Cache invalidation strategy

Action	Invalidation
Create entity	Invalidate list query for that entity type
Update entity	Invalidate both list and detail queries
Delete entity	Invalidate list query
Import CSV	Invalidate list query
Status change	Invalidate order list and detail queries

Query key conventions

// List queries
['employees', storeId]
['orders', { storeId, status }]
['rule-sets', clientId]

// Detail queries
['employee', employeeId]
['order', orderId]

// Aggregation queries
['reports', 'store-ops', { dateRange }]
['entitlements', employeeId, categoryId]

Error handling

React Query errors are handled at the component level:

const { data, error, isLoading } = useEmployees();

if (isLoading) return <LoadingSpinner />;
if (error) return <ErrorMessage error={error} />;
if (!data) return <EmptyState />;

return <EmployeeTable employees={data} />;

Optimistic updates

For critical UI responsiveness, some mutations use optimistic updates:

return useMutation({
  mutationFn: updateOrderStatus,
  onMutate: async (newStatus) => {
    await queryClient.cancelQueries({ queryKey: ['orders'] });
    const previous = queryClient.getQueryData(['orders']);
    queryClient.setQueryData(['orders'], (old) =>
      old.map(order => order.id === newStatus.id
        ? { ...order, status: newStatus.status }
        : order
      )
    );
    return { previous };
  },
  onError: (err, newStatus, context) => {
    queryClient.setQueryData(['orders'], context.previous);
  },
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['orders'] });
  },
});

What React Query does not manage

State	Managed by
Authentication session	better-auth + local state
UI state (modals, drawers)	React component state
Form state	React Hook Form
Theme / dark mode	CSS variables + React context
Global app settings	React context

Overview

System Architecture

Security

Business Engines

Notifications & Reports

Data

Operations

Engineering

React Query in MUZE

Provider setup

Cache tiers (Phase 2.12)

Query patterns

Fetching data

Creating data

Updating data

Cache invalidation strategy

Query key conventions

Error handling

Optimistic updates

What React Query does not manage

​React Query in MUZE

​Provider setup

​Cache tiers (Phase 2.12)

​Query patterns

​Fetching data

​Creating data

​Updating data

​Cache invalidation strategy

​Query key conventions

​Error handling

​Optimistic updates

​What React Query does not manage

React Query in MUZE

Provider setup

Cache tiers (Phase 2.12)

Query patterns

Fetching data

Creating data

Updating data

Cache invalidation strategy

Query key conventions

Error handling

Optimistic updates

What React Query does not manage