Status: Accepted Date: 2026-02-21
Context#
The OSHUN web app needs to manage several categories of state: authentication, server data (BFF responses), UI state (view navigation, modals), and domain- specific state (habit lists, session playback). We needed a strategy that scales across multiple domains without creating a monolithic store.
Decision#
We use a layered state architecture with no single global store:
-
Auth Context (
src/lib/auth-context.tsx) — React Context for authentication status, tokens, and user identity. Persisted to localStorage. -
React Query / TanStack Query (
src/lib/query-provider.tsx) — Server state management for all BFF API data. Handles caching, deduplication, background refetching, and optimistic updates. -
Component-local state (
useState) — View-level UI state within domain surfaces (active view, selected items, form inputs). Each domain surface manages its own view routing internally. -
Profile store — Minimal store for user profile and entitlements, used for access control decisions in domain routing.
Rationale#
Why not Redux/Zustand for everything?#
- Most app state is server state (BFF responses). React Query handles this better than manual stores — it provides caching, staleness, refetching, and pagination out of the box.
- Domain surfaces are code-split and isolated. A global store would create coupling between lazily-loaded domains.
- Authentication is a cross-cutting concern that fits naturally into React Context.
Why React Query over SWR?#
- Built-in support for infinite queries (activity feed pagination)
- Optimistic updates with rollback (notification mark-all-read)
- Configurable garbage collection (
gcTime) - Mutation hooks with cache invalidation
Why localStorage for auth?#
- Tokens need to persist across page reloads and browser restarts
- Dev mode uses a static dev token for local development without a running auth service
- Token expiration is checked client-side with a 60-second buffer before attempting refresh
Consequences#
- No single place to inspect all app state (trade-off for simplicity)
- Server state is always eventually consistent (stale data visible briefly)
- Domain surfaces can't easily share UI state (by design — domains are isolated)
- Auth context must be high in the provider tree since API hooks depend on tokens