Eve library

ADR-001: State Management Strategy

ADR

Revision 1

On this page

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:

  1. Auth Context (src/lib/auth-context.tsx) — React Context for authentication status, tokens, and user identity. Persisted to localStorage.

  2. 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.

  3. 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.

  4. 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