# Frontend Architecture

## Purpose
Explain the frontend structure, routing, state management, providers, and module organization in the React/Vite app.

## Code Locations (exact paths)
- Entry: `frontend/src/main.tsx`
- Root app/routing: `frontend/src/App.tsx`
- State (Zustand stores): `frontend/src/store/*` (authStore, siteStore, billingStore, settingsStore, onboardingStore, columnVisibilityStore, pageSizeStore)
- API layer: `frontend/src/api/*` and `frontend/src/services/api.ts`
- Layout and components: `frontend/src/layout/*`, `frontend/src/components/*`
- Pages: `frontend/src/pages/*` (modules and settings)
- Config: `frontend/src/config/*`
- Styles: `frontend/src/index.css`, `frontend/src/styles/igny8-colors.css`

## High-Level Responsibilities
- Provide SPA routing with protected routes and module guards.
- Maintain global state for auth, site context, billing, settings, UI preferences via Zustand.
- Lazy-load module pages to optimize initial load.
- Wrap the app with providers for theming, toasts, header metrics, error boundary, and router.

## Detailed Behavior
- Entry (`main.tsx`):
  - Imports global styles and vendor CSS (Swiper, Flatpickr).
  - Wraps the app with `ErrorBoundary`, `ThemeProvider`, `HeaderMetricsProvider`, `ToastProvider`, `BrowserRouter`, then renders `<App />` via React 18 `createRoot`.
- Routing (`App.tsx`):
  - Uses `BrowserRouter` (in main) with `<Routes>`/`<Route>` inside App.
  - Public routes: `/signin`, `/signup`.
  - Protected routes wrapped by `ProtectedRoute` → `AppLayout`; `ModuleGuard` used per-module.
  - Default dashboard `/` loads `Dashboard/Home`.
  - Planner routes redirect `/planner` → `/planner/keywords`; writer routes redirect `/writer` → `/writer/tasks`.
  - Extensive lazy-loaded pages for Planner, Writer, Automation, Linker, Optimizer, Thinker (system), Billing, Admin, Settings, Sites, Help, Reference, Components, UI elements, etc.
  - `GlobalErrorDisplay` and `LoadingStateMonitor` mounted globally; `ScrollToTop` for navigation changes.
  - Auth refresh: on mount, if authenticated with token, calls `refreshUser`; on failure with missing credentials message, ignores; otherwise logs out.
- State (Zustand examples):
  - `authStore`: persists user/token/refreshToken; `login`/`register` hit `/api/v1/auth/...`; enforces account and active plan presence; `refreshUser` fetches user from `/api/v1/auth/users/me/`; `refreshToken` hits `/api/v1/auth/refresh/`; logout clears all auth fields.
  - `siteStore`: stores current site/sector and list; used for context across modules.
  - `billingStore`, `settingsStore`, `onboardingStore`, `columnVisibilityStore`, `pageSizeStore`: manage billing data, settings flags, onboarding steps, table visibility, pagination sizes.
- API layer:
  - `services/api.ts` provides `fetchAPI` helper for authenticated calls (uses token from auth store, handles JSON, throws on non-OK).
  - `api/*` modules define typed client calls per domain (auth, planner, writer, etc.).
- Layout/components:
  - `AppLayout` wraps sidebar/header/content; `ModuleGuard` enforces module access flags; `ProtectedRoute` enforces auth.
  - UI utilities: toasts, error boundary, global loading monitor, scroll-to-top, etc.

## Data Structures / Models Involved (no code)
- Frontend state shapes defined in Zustand stores (auth user, site context, billing info, settings).

## Execution Flow
- App bootstrap → providers → App routes → ProtectedRoute checks auth → ModuleGuard checks module access → lazy-loaded pages fetch data via `api/*` using tokens from authStore → state updates via stores.

## Cross-Module Interactions
- Auth store tokens used by fetchAPI for all modules.
  - Site store context influences planner/writer/automation calls.
  - Billing store interacts with billing endpoints; settings store influences UI/features; onboarding/table stores affect page rendering.

## State Transitions
- Auth: login/register → set user/token; refresh → update tokens/user; logout clears.
- Site context changes update current site/sector for downstream calls.
- Billing/settings/onboarding/table state mutate via respective store actions.

## Error Handling
- `GlobalErrorDisplay` shows errors; `LoadingStateMonitor` tracks loading; `ProtectedRoute` logs out on failed refresh.
- `fetchAPI` throws on non-OK; authStore catches and surfaces messages; ModuleGuard/ProtectedRoute handle unauthorized access.

## Tenancy Rules
- Enforced via tokens and site context; ModuleGuard and ProtectedRoute rely on backend responses (account/plan) and module flags.

## Billing Rules
- Auth store enforces active plan on login; billing store/pages call billing endpoints for balances/transactions/purchases.

## Background Tasks / Schedulers
- None on frontend; relies on backend/Celery for async work; uses Suspense for lazy loading.

## Key Design Considerations
- Lazy-loaded routes minimize initial bundle.
- Zustand persistence keeps auth/session across reloads.
- Providers wrap app for theming, toasts, error boundary to improve UX stability.

## How Developers Should Work With This Module
- Add routes inside `App.tsx` under ProtectedRoute for authenticated pages; use ModuleGuard for module-gated pages.
- Create new stores in `src/store` for shared state; use `fetchAPI` for authenticated requests.
- Keep lazy loading for heavy pages and maintain Suspense fallbacks where needed.