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

84
docs/30-FRONTEND/FRONTEND-ARCHITECTURE.md Normal file
View File

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