Frontend Context + TanStack Vision

Status: active baseline.

1) Context model (app-level state only)

Use src/context/* for shared app state that many pages read and mutate:

• context/auth/* -> session identity, current user, auth actions, user permission refresh
• context/system/* -> system permission catalog and system-level shared metadata
• context/notifications/* -> global notifications list + unread count
• context/ui/* -> global UI/session notice state
• context/theme/* -> theme state and persistence

Rule: avoid putting page datasets (lists/details/tables/charts) into context.

2) TanStack Query model (server-state)

Use TanStack Query for server-state pages and datasets:

• Users list/detail
• Maintenance list/detail
• Analytics datasets
• Logs/audit pages
• Any GET-heavy data with cache/re-fetch needs

2.1 Query key policy

Use stable, domain-first keys:

• ['users', params]
• ['user', userId]
• ['maintenance', params]
• ['system', 'audit', params]

Do not use random/unstable objects in keys.

2.2 Mutation + invalidation policy

After mutation, invalidate only affected keys:

• create/update user -> invalidate ['users'] and ['user', id]
• update user permissions -> invalidate ['user', id] and any permission-dependent views

Avoid global invalidation unless truly needed.

3) What not to do

• Do not duplicate the same data in context and query cache.
• Do not call APIs directly in many components when a shared query hook exists.
• Do not store large table data in context.
• Do not use TanStack for pure UI state (modals, toasts, current tab, etc.).

4) Recommended hook style

Create domain hooks under src/domains/<domain>/hooks/:

• useUsersListQuery(params)
• useUserDetailQuery(userId)
• useUpdateUserMutation()

Keep API calls in service modules; hooks orchestrate cache/query behavior.

5) Migration plan

1. Add QueryProvider (done).
2. Migrate users pages first (/users, /users/:id) to query hooks.
3. Migrate notifications page/list to query hooks (context still keeps unread/global view state).
4. Migrate system pages (audit/logs/monitoring) with query keys and pagination strategy.

6) DX/maintainability guardrails

• New shared state proposal must answer: "Context or Query?" with reason.
• New query must define query key and invalidation behavior in PR notes.
• Keep naming short and consistent (useXQuery, useXMutation, XContextProvider).