# ADR-001: State Management Strategy

**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
