igny8/docs/30-FRONTEND/COMPONENTS.md

Global UI Components and Providers

Purpose

Describe global layout, guards, and utility components/providers used throughout the frontend.

Code Locations (exact paths)

• App composition and routing: frontend/src/App.tsx
• Entry/providers: frontend/src/main.tsx
• Layout: frontend/src/layout/AppLayout.tsx, frontend/src/layout/AppSidebar.tsx, frontend/src/layout/AppHeader.tsx (and related layout files)
• Guards: frontend/src/components/auth/ProtectedRoute.tsx, frontend/src/components/common/ModuleGuard.tsx
• Global utilities: frontend/src/components/common/ScrollToTop.tsx, frontend/src/components/common/GlobalErrorDisplay.tsx, frontend/src/components/common/LoadingStateMonitor.tsx, frontend/src/components/common/ErrorBoundary.tsx
• Providers: frontend/src/context/ThemeContext.tsx, frontend/src/context/HeaderMetricsContext.tsx, frontend/src/components/ui/toast/ToastContainer.tsx

High-Level Responsibilities

• Wrap the app with error handling, theming, metrics, toasts, and routing.
• Enforce authentication and module access at the route level.
• Provide global UI behaviors (scroll reset, error banner, loading monitor).
• Supply consistent layout (sidebar/header/content) for protected areas.

Detailed Behavior

• Providers (main.tsx):
  • ErrorBoundary wraps the entire app.
  • ThemeProvider supplies theme context.
  • HeaderMetricsProvider supplies header metrics context.
  • ToastProvider exposes toast notifications.
  • BrowserRouter provides routing; renders <App />.
• Routing shell (App.tsx):
  • GlobalErrorDisplay renders global errors; LoadingStateMonitor tracks loading states.
  • ScrollToTop resets scroll on route changes.
  • Public routes: /signin, /signup.
  • Protected routes: wrapped in ProtectedRoute → AppLayout; ModuleGuard used per-module.
  • Lazy-loaded module pages inside routes; ModuleGuard enforces module access flags.
• Guards:
  • ProtectedRoute: checks useAuthStore for authentication; redirects unauthenticated users to sign-in; logs out on failed refresh in App effect.
  • ModuleGuard: gates module pages based on module enable settings/permissions.
• Layout:
  • AppLayout composes sidebar/header/content; AppSidebar uses auth store for user/nav; header components provide top-level actions and metrics.
• Utilities:
  • ScrollToTop listens to route changes and scrolls to top.
  • GlobalErrorDisplay shows global error banners.
  • LoadingStateMonitor tracks loading indicators globally.
  • ToastProvider supplies toast UI primitives for notifications.

Data Structures / Models Involved (no code)

• Context values from theme, header metrics, toast providers; auth state from authStore; module enable settings from settingsStore.

Execution Flow

• App bootstrap wraps providers → routes render → ProtectedRoute checks auth → ModuleGuard checks module access → layout renders with sidebar/header → pages load lazily and fetch data.

Cross-Module Interactions

• Auth/module settings drive guards; toasts/errors/loading monitors are available to all pages; layout navigation links modules.

Error Handling

• ErrorBoundary catches render errors.
  • GlobalErrorDisplay surfaces application-level errors.
  • ProtectedRoute logs out on failed refresh in App effect; unauthorized users are redirected.

Tenancy Rules

• Enforced via backend auth and module enable settings; guards rely on auth/module settings to gate access.

Billing Rules

• None in UI components; billing info shown in pages that consume billing store/endpoints.

Background Tasks / Schedulers

• None; components react to store state and router changes.

Key Design Considerations

• Provider stack covers theme, metrics, toasts, error boundary, routing.
• Guards ensure unauthorized access is blocked at the route level.
• Global utilities avoid repeated boilerplate for scroll/error/loading behaviors.

How Developers Should Work With This Module

• Add new protected pages under ProtectedRoute and wrap with ModuleGuard when module-scoped.
• Use existing toast/error/loading utilities instead of duplicating.
• Keep provider order consistent (ErrorBoundary → Theme/Header/Toast → Router → App).