77 lines
4.2 KiB
Markdown
77 lines
4.2 KiB
Markdown
# 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).
|
|
|