85 lines
5.3 KiB
Markdown
85 lines
5.3 KiB
Markdown
# 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.
|
|
|