salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs re-org

Browse Source
This commit is contained in:
IGNY8 VPS (Salman)
2025-12-09 13:26:35 +00:00
parent 4d13a57068
commit 6a4f95c35a
231 changed files with 11353 additions and 31152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/90-ARCHIVED/master-docs-original/30-frontend/STATE-MANAGEMENT.md Normal file
View File

@@ -0,0 +1,90 @@
# 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).