# 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).