# State Management

## Purpose
Describe how the frontend manages global state with Zustand stores, including authentication, site context, billing, and settings.

## Code Locations (exact paths)
- Auth store: `frontend/src/store/authStore.ts`
- Site store: `frontend/src/store/siteStore.ts`
- Billing store: `frontend/src/store/billingStore.ts`
- Settings store: `frontend/src/store/settingsStore.ts`
- Other UI/state stores: `frontend/src/store/onboardingStore.ts`, `columnVisibilityStore.ts`, `pageSizeStore.ts`, `settingsStore.ts`, etc.

## High-Level Responsibilities
- Persist authentication state (user, tokens), refresh sessions, and enforce account/plan presence.
- Track the active site (and sector via sector store) across modules, with persistence and change events.
- Fetch and cache billing balances/usage/limits.
- Load and update account/module settings with coalesced fetches and persistence.

## Detailed Behavior
- `authStore`:
  - Persists `user`, `token`, `refreshToken`, `isAuthenticated`, `loading`.
  - `login(email,password)`: POST `/api/v1/auth/login/`; stores tokens/user; errors mapped to PLAN_REQUIRED/ACCOUNT_REQUIRED/AUTH_FAILED; resets loading on error.
  - `register(data)`: POST `/api/v1/auth/register/`; stores tokens/user; resets loading on error.
  - `refreshToken()`: POST `/api/v1/auth/refresh/`; updates access token; attempts `refreshUser`; logs out on failure.
  - `refreshUser()`: GET `/api/v1/auth/users/me/`; requires account+plan; updates user or logs out on auth failure; clears loading guard.
  - `logout()`: clears all auth fields.
- `siteStore`:
  - Persists `activeSite`; stores `loading`/`error`.
  - `setActiveSite(site)`: sets/persists site, dispatches `siteChanged` event, triggers sector store load for the site.
  - `loadActiveSite()`: fetches sites via `fetchSites`; picks prior site if still active, else first active; persists selection.
  - `refreshActiveSite()`: refreshes current site from server; reloads if inactive/missing.
- `billingStore`:
  - Holds `balance`, `usageSummary`, `usageLimits`, `loading`/`error`, `lastUpdated`.
  - `loadBalance()`: calls `getCreditBalance`; keeps prior balance during retry; sets `lastUpdated`.
  - `loadUsageSummary(startDate?, endDate?)`: calls `getCreditUsageSummary`; updates summary.
  - `loadUsageLimits()`: calls `getCreditUsageLimits`; tolerates 404 by returning null; records errors otherwise.
  - `reset()`: clears billing state.
- `settingsStore`:
  - Persists `accountSettings`, `moduleSettings`, `moduleEnableSettings`, `loading`/`error`.
  - Account settings: load all, load one, create/update with create/update endpoints; handles typed errors (not found vs validation).
  - Module settings: load/update per module; stores per-module map.
  - Module enable settings: caches for 60s, coalesces concurrent fetches; `isModuleEnabled` helper.
  - `reset()` clears settings state.
- Other stores:
  - `onboardingStore`, `columnVisibilityStore`, `pageSizeStore` manage UI/onboarding/table preferences (see respective files for exact fields/actions).

## Data Structures / Models Involved (no code)
- Store state interfaces defined in each file (auth user shape, site, billing balance/usage, settings maps).

## Execution Flow
- Components/hooks read/write state via `useXStore` hooks.
- Auth flows call store actions, which perform fetches and update state; ProtectedRoute/ModuleGuard rely on auth and settings/module enable flags.
- Site changes dispatch `siteChanged` for downstream listeners and trigger sector loading.
- Billing/settings loads fetch data on demand and cache/persist where configured.

## Cross-Module Interactions
- Auth tokens consumed by `fetchAPI` for all API calls.
- Active site influences planner/writer/automation calls via query params/context.
- Module enable settings influence `ModuleGuard`.
- Billing data feeds billing pages and credit displays.

## State Transitions
- Auth: unauthenticated → login/register → authenticated; refresh updates tokens/user; logout clears.
- Site: load/refresh/set updates `activeSite` and notifies listeners.
- Billing/settings: load/update actions mutate cached maps and loading/error flags.

## Error Handling
- Auth store resets loading on all error paths; throws descriptive errors.
- Billing store tolerates missing limits (404) and surfaces messages; balance retry preserves prior state.
- Settings store differentiates not-found vs validation errors; stores messages in `error`.

## Tenancy Rules
- Auth store requires account+plan; site store filters on accessible sites; billing/settings calls use authenticated endpoints tied to the user’s account.

## Billing Rules
- Enforced via backend; billing store reads balances/usage/limits and does not mutate credits.

## Background Tasks / Schedulers
- None; all store actions are user-driven fetches with immediate state updates.

## Key Design Considerations
- Zustand `persist` used for auth/site/settings to survive reloads.
- Guarded loading flags and error handling prevent stuck states.
- Site changes broadcast events for dependent components/stores.

## How Developers Should Work With This Module
- Use existing store actions for auth/site/billing/settings instead of duplicating fetch logic.
- When adding new shared state, create a dedicated store in `src/store` and persist only needed slices.
- Keep error/reset semantics consistent (always clear loading on failure).