igny8/master-docs/30-frontend/FRONTEND-ARCHITECTURE.md

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.