slp-modular-cms/aidlc-docs/features/cms-frontend/inception/application-design/components.md

# Component Definitions — CMS Frontend

## Backend Components (Unit 0)

### CorsPolicy
- **Purpose**: Configure Cross-Origin Resource Sharing for the frontend SPA
- **Responsibilities**:
  - Allow the configured frontend origin(s) from `appsettings.json → AllowedOrigins`
  - Allow credentials (`AllowCredentials()`) so the browser sends the httpOnly cookie
  - Allow required HTTP methods and headers
- **Location**: `src/SlpModularCms.Api/Extensions/ServiceCollectionExtensions.cs` (extended)
- **Configuration**: `appsettings.json → Cors:AllowedOrigins[]`, `appsettings.Development.json` (dev origins), `appsettings.local.json` (developer override)

### AuthController (updated)
- **Purpose**: Authentication HTTP endpoints — updated to set/clear httpOnly cookie
- **Responsibilities**:
  - `Login`: Call `IAuthService.AuthenticateAsync()`, set `refreshToken` httpOnly cookie, return access token + user info only in body
  - `Refresh`: Read `refreshToken` from cookie (not request body), call `IAuthService.RefreshTokenAsync()`, set new cookie, return new access token
  - `Revoke`: Call `IAuthService.RevokeTokenAsync()` with cookie value, clear the cookie
- **Location**: `src/SlpModularCms.Modules.Identity/Controllers/AuthController.cs`

### AuthService (updated)
- **Purpose**: Core authentication business logic — updated for cookie-based refresh flow
- **Responsibilities**:
  - `RefreshTokenAsync(accessToken, refreshToken)` — signature unchanged; cookie reading is the controller's responsibility
  - No other changes to service layer

---

## Frontend Components (Units 1–6)

### Infrastructure Layer

#### ApiClient
- **Purpose**: Centralised HTTP client — all API calls go through this module
- **Responsibilities**:
  - Base URL from `import.meta.env.VITE_API_BASE_URL`
  - Attach `Authorization: Bearer {accessToken}` header on authenticated requests
  - Intercept 401 responses — trigger token refresh via `AuthContext.refresh()`, retry original request once
  - Expose typed request functions used by TanStack Query
  - Send requests with `credentials: 'include'` so the browser includes the httpOnly cookie
- **Location**: `frontend/src/api/client.ts`

#### AuthContext
- **Purpose**: React Context providing authentication state to the entire app
- **Responsibilities**:
  - Store in-memory `accessToken` (string | null) — never persisted to localStorage
  - Store authenticated user: `{ id, email, name, role, isActive }`
  - Expose `login(email, password)`, `logout()`, `refresh()` methods
  - On app mount: call `/auth/refresh` via httpOnly cookie to restore session
  - Provide `isAuthenticated`, `isLoading`, `user`, `role` derived state
- **Location**: `frontend/src/auth/AuthContext.tsx` + `frontend/src/auth/useAuth.ts`

#### RouterConfig
- **Purpose**: TanStack Router file-based route tree with integrated guards
- **Responsibilities**:
  - File-based route structure under `frontend/src/routes/`
  - Root route checks `InitGuard` (setup status) before rendering any child
  - Authenticated routes wrapped with `ProtectedRoute` check
  - Role-specific routes wrapped with `RoleGuard` check
  - Redirect to `/login` with `?redirect=` param on auth failure
- **Location**: `frontend/src/routes/` (file-based), `frontend/src/routeTree.gen.ts` (generated)

---

### Auth & Guard Components

#### ProtectedRoute
- **Purpose**: Redirect unauthenticated users to `/login`
- **Responsibilities**:
  - Read `isAuthenticated` from `AuthContext`
  - If not authenticated: redirect to `/login?redirect={currentPath}`
  - If loading (session restore in progress): show loading spinner — no flash of content
  - If authenticated: render child route
- **Location**: `frontend/src/auth/ProtectedRoute.tsx`

#### RoleGuard
- **Purpose**: Restrict routes to specific roles
- **Responsibilities**:
  - Accept `allowedRoles: string[]` prop
  - Read `user.role` from `AuthContext`
  - If role not in `allowedRoles`: redirect to `/403`
  - If role allowed: render child route
- **Location**: `frontend/src/auth/RoleGuard.tsx`

#### InitGuard
- **Purpose**: Redirect to `/setup` if the system is not initialized
- **Responsibilities**:
  - On first app render: call `GET /setup/status`
  - If `initialized: false`: redirect all routes to `/setup`
  - If `initialized: true`: allow normal routing
  - Show loading state during check
  - Handle API failure with error page + retry
- **Location**: `frontend/src/auth/InitGuard.tsx`

---

### Layout Components

#### AppLayout
- **Purpose**: Authenticated shell layout wrapping all protected pages
- **Responsibilities**:
  - Render `Sidebar` on the left + `<Outlet />` (page content) on the right
  - Responsive: full sidebar on desktop, collapsed/hamburger on mobile
- **Location**: `frontend/src/components/layout/AppLayout.tsx`

#### Sidebar
- **Purpose**: Navigation sidebar with role-filtered links
- **Responsibilities**:
  - Read `user.role` from `AuthContext` to filter navigation items
  - Navigation items: Dashboard (all), User Management (Owner/Admin), System Settings (Owner), CMS (Owner), Profile (all)
  - Logout button: calls `AuthContext.logout()`
  - Theme toggle: calls `ThemeProvider.toggle()`
  - Highlight active route
  - Collapsible on mobile
- **Location**: `frontend/src/components/layout/Sidebar.tsx`

#### ThemeProvider
- **Purpose**: Dark/light theme management
- **Responsibilities**:
  - Wrap app with `next-themes` provider
  - Persist theme preference in `localStorage` under key `cms-theme`
  - Default to system preference
  - Expose `useTheme()` hook via next-themes
- **Location**: `frontend/src/components/layout/ThemeProvider.tsx`

---

### Page Components

#### LoginPage (`/login`)
- **Purpose**: Unauthenticated login form
- **Responsibilities**: Email + password form, react-hook-form + zod validation, calls `AuthContext.login()`
- **Location**: `frontend/src/routes/login.tsx`

#### SetupPage (`/setup`)
- **Purpose**: First-time system initialization form
- **Responsibilities**: Email + password form (owner creation), calls `POST /setup/owner`, redirects to `/login` on success
- **Location**: `frontend/src/routes/setup.tsx`

#### InviteCompletePage (`/invite/complete`)
- **Purpose**: Invitation token completion form
- **Responsibilities**: Validate token via `GET /users/validate-invitation`, show display name + password form, call `POST /users/complete-setup`
- **Location**: `frontend/src/routes/invite.complete.tsx`

#### DashboardPage (`/`)
- **Purpose**: Authenticated home page
- **Responsibilities**: Welcome widget (user name + role), availability status widget (TanStack Query)
- **Location**: `frontend/src/routes/index.tsx`

#### UsersPage (`/users`)
- **Purpose**: User management page (Owner/Admin only)
- **Responsibilities**: User list (TanStack Query), InviteUserDialog (invite form + share link step)
- **Location**: `frontend/src/routes/users.tsx`

#### ProfilePage (`/profile`)
- **Purpose**: Read-only profile page
- **Responsibilities**: Show `user.name`, `user.email`, `user.role` from `AuthContext`
- **Location**: `frontend/src/routes/profile.tsx`

#### SettingsPage (`/settings`)
- **Purpose**: System settings page (Owner only)
- **Responsibilities**: Show availability status (TanStack Query), show initialized state, placeholder sections
- **Location**: `frontend/src/routes/settings.tsx`

#### CmsPage (`/cms`)
- **Purpose**: CMS management placeholder (Owner only)
- **Responsibilities**: Work-in-progress placeholder with description of future multi-CMS management
- **Location**: `frontend/src/routes/cms.tsx`

#### NotFoundPage (`/404` or catch-all)
- **Purpose**: 404 error page
- **Location**: `frontend/src/routes/$404.tsx`

#### AccessDeniedPage (`/403`)
- **Purpose**: 403 forbidden page shown when role guard fails
- **Location**: `frontend/src/routes/403.tsx`

---

### Shared UI Components

#### InviteUserDialog
- **Purpose**: Modal dialog for inviting a new user
- **Responsibilities**: Two-step: (1) invite form with email + role, (2) share invite link with copy button
- **Location**: `frontend/src/components/users/InviteUserDialog.tsx`

#### AvailabilityStatusBadge
- **Purpose**: Colour-coded availability status indicator
- **Responsibilities**: Display Available (green) / Maintenance (yellow) / Unavailable (red) with reason
- **Location**: `frontend/src/components/shared/AvailabilityStatusBadge.tsx`

#### ErrorBoundary (Global + Per-Page)
- **Purpose**: Catch unexpected React errors
- **Responsibilities**: Global boundary at app root; per-page boundaries for isolated page failures; show user-friendly fallback UI
- **Location**: `frontend/src/components/error/ErrorBoundary.tsx`