@rashidee/co2 1.2.5

package/plugin/skills/mockgen-shadcn/references/admin-layout-template.md

@@ -0,0 +1,1467 @@
+# Admin Layout Architecture — Vite + React 19 + shadcn/ui
+
+The mockup application uses **Vite** as the build tool (dev server for design iteration
+only), **React 19** with **TypeScript** for UI components, **React Router v7** for
+client-side navigation, **shadcn/ui** (Radix UI + Tailwind CSS) for the component library,
+**Lucide React** for icons, and **next-themes** for dark mode support.
+
+The app is generated with `base`/`basename` = `/{{APP_SLUG}}/` and **built**
+(`npm run build`); the shared **Mockup Hub** (`<root>/mockup/server.js` — see
+[mockup-hub-template.md](mockup-hub-template.md)) serves the `dist/` output at
+`/{{APP_SLUG}}/...` with SPA fallback. `{{APP_SLUG}}` is replaced at generation time with
+the app folder name minus its leading `<number>_` prefix.
+
+---
+
+## File Structure
+
+```
+mockup/
+  .gitignore
+  mockup-manifest.json    # Hub discovery manifest (see mockup-hub-template.md)
+  dist/                   # Built output served by the hub (npm run build; gitignored)
+  package.json
+  vite.config.ts
+  tsconfig.json
+  tsconfig.app.json
+  tsconfig.node.json
+  tailwind.config.js
+  postcss.config.js
+  components.json
+  index.html
+  MOCKUP.html
+  public/
+    reports/                             # Report layouts (if applicable)
+  src/
+    main.tsx
+    App.tsx
+    index.css
+    lib/
+      utils.ts
+    components/
+      ui/
+        button.tsx
+        card.tsx
+        table.tsx
+        badge.tsx
+        input.tsx
+        label.tsx
+        select.tsx
+        dialog.tsx
+        dropdown-menu.tsx
+        avatar.tsx
+        separator.tsx
+        tabs.tsx
+        switch.tsx
+        tooltip.tsx
+        breadcrumb.tsx
+        pagination.tsx
+        sheet.tsx
+      layout/
+        app-layout.tsx
+        app-header.tsx
+        app-sidebar.tsx
+        app-footer.tsx
+        sidebar-config.ts
+    pages/
+      {role-kebab-case}/
+        home.tsx
+        profile.tsx
+        account.tsx
+        notifications.tsx
+        {module-kebab-case}.tsx
+        {module-kebab-case}-detail.tsx
+        {module-kebab-case}-create.tsx
+        {module-kebab-case}-edit.tsx
+        ...
+```
+
+---
+
+## Placeholders Reference
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{{APP_NAME}}` | Application name (e.g., "Hub Middleware") |
+| `{{APP_SLUG}}` | App slug used as URL base path (e.g., "hub_middleware") — replaced at generation time |
+| `{{APP_INITIALS}}` | Application initials (e.g., "HM") |
+| `{{PAGE_TITLE}}` | Screen title (e.g., "Location Information") |
+| `{{COPYRIGHT_YEAR}}` | Current year |
+| `{{VERSION}}` | Latest version from PRD.md |
+| `{{DESIGN_PRIMARY}}` | Primary color hex from design system |
+| `{{DESIGN_SECONDARY}}` | Secondary color hex from design system |
+| `{{DESIGN_ACCENT}}` | Accent/CTA color hex |
+| `{{HEADING_FONT}}` | Heading font family |
+| `{{BODY_FONT}}` | Body font family |
+| `{{GOOGLE_FONTS_URL}}` | Google Fonts import URL |
+
+---
+
+## package.json Template
+
+```json
+{
+  "name": "{{APP_SLUG}}-mockup",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "description": "UI Mockup (React + shadcn/ui) — generated by mockgen-shadcn; built dist/ is served by the Mockup Hub at <root>/mockup",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.1.0",
+    "lucide-react": "^0.468.0",
+    "next-themes": "^0.4.4",
+    "@radix-ui/react-avatar": "^1.1.2",
+    "@radix-ui/react-dialog": "^1.1.4",
+    "@radix-ui/react-dropdown-menu": "^2.1.4",
+    "@radix-ui/react-label": "^2.1.1",
+    "@radix-ui/react-select": "^2.1.4",
+    "@radix-ui/react-separator": "^1.1.1",
+    "@radix-ui/react-switch": "^1.1.2",
+    "@radix-ui/react-tabs": "^1.1.2",
+    "@radix-ui/react-tooltip": "^1.1.6",
+    "@radix-ui/react-slot": "^1.1.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "typescript": "~5.7.0",
+    "vite": "^6.0.0"
+  }
+}
+```
+
+---
+
+## vite.config.ts Template
+
+The `base` option is REQUIRED — it makes the built app servable by the Mockup Hub at
+`/{{APP_SLUG}}/` (and the dev server serve at `http://localhost:5173/{{APP_SLUG}}/`).
+
+```typescript
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import path from "path";
+
+export default defineConfig({
+  base: "/{{APP_SLUG}}/",
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+});
+```
+
+---
+
+## tsconfig.json Template
+
+```json
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}
+```
+
+## tsconfig.app.json Template
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}
+```
+
+## tsconfig.node.json Template
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}
+```
+
+---
+
+## tailwind.config.js Template
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+export default {
+  darkMode: ["class"],
+  content: [
+    "./index.html",
+    "./src/**/*.{ts,tsx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))",
+        },
+        secondary: {
+          DEFAULT: "hsl(var(--secondary))",
+          foreground: "hsl(var(--secondary-foreground))",
+        },
+        destructive: {
+          DEFAULT: "hsl(var(--destructive))",
+          foreground: "hsl(var(--destructive-foreground))",
+        },
+        muted: {
+          DEFAULT: "hsl(var(--muted))",
+          foreground: "hsl(var(--muted-foreground))",
+        },
+        accent: {
+          DEFAULT: "hsl(var(--accent))",
+          foreground: "hsl(var(--accent-foreground))",
+        },
+        popover: {
+          DEFAULT: "hsl(var(--popover))",
+          foreground: "hsl(var(--popover-foreground))",
+        },
+        card: {
+          DEFAULT: "hsl(var(--card))",
+          foreground: "hsl(var(--card-foreground))",
+        },
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+      fontFamily: {
+        heading: ["{{HEADING_FONT}}", "sans-serif"],
+        body: ["{{BODY_FONT}}", "sans-serif"],
+      },
+    },
+  },
+  plugins: [],
+};
+```
+
+---
+
+## postcss.config.js Template
+
+```javascript
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+```
+
+---
+
+## components.json Template (shadcn/ui config)
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/index.css",
+    "baseColor": "zinc",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui"
+  }
+}
+```
+
+---
+
+## index.html Template (Vite entry)
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_NAME}}</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="{{GOOGLE_FONTS_URL}}" rel="stylesheet" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+---
+
+## src/index.css Template
+
+The CSS variables define the shadcn/ui color system. Replace HSL values to match the
+design system from Step 2. The variable names are used by all shadcn/ui components.
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 240 10% 3.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 240 10% 3.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 240 10% 3.9%;
+    --primary: 240 5.9% 10%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 240 4.8% 95.9%;
+    --secondary-foreground: 240 5.9% 10%;
+    --muted: 240 4.8% 95.9%;
+    --muted-foreground: 240 3.8% 46.1%;
+    --accent: 240 4.8% 95.9%;
+    --accent-foreground: 240 5.9% 10%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 5.9% 90%;
+    --input: 240 5.9% 90%;
+    --ring: 240 5.9% 10%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 240 10% 3.9%;
+    --foreground: 0 0% 98%;
+    --card: 240 10% 3.9%;
+    --card-foreground: 0 0% 98%;
+    --popover: 240 10% 3.9%;
+    --popover-foreground: 0 0% 98%;
+    --primary: 0 0% 98%;
+    --primary-foreground: 240 5.9% 10%;
+    --secondary: 240 3.7% 15.9%;
+    --secondary-foreground: 0 0% 98%;
+    --muted: 240 3.7% 15.9%;
+    --muted-foreground: 240 5% 64.9%;
+    --accent: 240 3.7% 15.9%;
+    --accent-foreground: 0 0% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 3.7% 15.9%;
+    --input: 240 3.7% 15.9%;
+    --ring: 240 4.9% 83.9%;
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-family: "{{BODY_FONT}}", sans-serif;
+  }
+  h1, h2, h3, h4, h5, h6 {
+    font-family: "{{HEADING_FONT}}", sans-serif;
+  }
+}
+```
+
+> **Design system integration**: When a design system provides custom colors (hex),
+> convert them to HSL values for the CSS variables. For example, primary color `#1E40AF`
+> becomes `--primary: 221.2 83.2% 53.3%`. Apply the design system's primary, secondary,
+> and accent colors to the corresponding CSS variables.
+
+---
+
+## src/lib/utils.ts Template
+
+```typescript
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+---
+
+## src/main.tsx Template
+
+```tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import { ThemeProvider } from "next-themes";
+import App from "./App";
+import "./index.css";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <BrowserRouter basename="/{{APP_SLUG}}">
+      <ThemeProvider attribute="class" defaultTheme="light" enableSystem>
+        <App />
+      </ThemeProvider>
+    </BrowserRouter>
+  </StrictMode>
+);
+```
+
+> The `basename` MUST match the Vite `base` — all internal `<Link to="/{role}/...">`
+> paths stay unchanged; React Router resolves them under `/{{APP_SLUG}}` automatically.
+
+---
+
+## src/App.tsx Template
+
+Defines all routes using React Router. The `AppLayout` component wraps all authenticated
+role pages.
+
+```tsx
+import { Routes, Route, Navigate } from "react-router-dom";
+import { AppLayout } from "@/components/layout/app-layout";
+
+// Import all page components — grouped by role
+// === Hub Administrator ===
+import HubAdminHome from "@/pages/hub-administrator/home";
+import HubAdminProfile from "@/pages/hub-administrator/profile";
+import HubAdminAccount from "@/pages/hub-administrator/account";
+import HubAdminNotifications from "@/pages/hub-administrator/notifications";
+// ... module pages ...
+
+// === Hub Operation Support ===
+// ... repeat for each role ...
+
+function App() {
+  return (
+    <Routes>
+      {/* Landing — redirect to first role's home */}
+      <Route path="/" element={<Navigate to="/hub-administrator/home" replace />} />
+
+      {/* Hub Administrator */}
+      <Route path="/hub-administrator" element={<AppLayout role="hub-administrator" />}>
+        <Route index element={<Navigate to="home" replace />} />
+        <Route path="home" element={<HubAdminHome />} />
+        <Route path="profile" element={<HubAdminProfile />} />
+        <Route path="account" element={<HubAdminAccount />} />
+        <Route path="notifications" element={<HubAdminNotifications />} />
+        {/* Module pages */}
+        {/* <Route path="location-information" element={<HubAdminLocationInformation />} /> */}
+        {/* <Route path="location-information-detail" element={<HubAdminLocationInformationDetail />} /> */}
+        {/* ... */}
+      </Route>
+
+      {/* Hub Operation Support */}
+      {/* <Route path="/hub-operation-support" element={<AppLayout role="hub-operation-support" />}> */}
+      {/*   ... */}
+      {/* </Route> */}
+
+      {/* Catch-all */}
+      <Route path="*" element={<Navigate to="/" replace />} />
+    </Routes>
+  );
+}
+
+export default App;
+```
+
+> **Route generation**: For each role and page in the screen plan, generate a complete
+> import statement and `<Route>` entry. The comments above are placeholders — replace
+> with actual routes.
+
+---
+
+## src/components/layout/app-layout.tsx Template
+
+```tsx
+import { useState } from "react";
+import { Outlet } from "react-router-dom";
+import { AppHeader } from "./app-header";
+import { AppSidebar } from "./app-sidebar";
+import { AppFooter } from "./app-footer";
+
+interface AppLayoutProps {
+  role: string;
+}
+
+export function AppLayout({ role }: AppLayoutProps) {
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
+
+  return (
+    <div className="min-h-screen flex flex-col bg-background">
+      {/* Header */}
+      <AppHeader role={role} />
+
+      {/* Body: Sidebar + Main */}
+      <div className="flex pt-16 min-h-[calc(100vh-4rem)]">
+        {/* Sidebar */}
+        <AppSidebar
+          role={role}
+          collapsed={sidebarCollapsed}
+          onToggle={() => setSidebarCollapsed(!sidebarCollapsed)}
+        />
+
+        {/* Main content */}
+        <main
+          className={cn(
+            "flex-1 flex flex-col min-w-0 transition-all duration-200",
+            sidebarCollapsed ? "ml-16" : "ml-64"
+          )}
+        >
+          {/* Page content (React Router Outlet) */}
+          <div className="flex-1 flex flex-col">
+            <Outlet />
+          </div>
+
+          {/* Footer */}
+          <AppFooter />
+        </main>
+      </div>
+    </div>
+  );
+}
+```
+
+> **Note**: Import `cn` from `@/lib/utils` at the top of the file.
+
+---
+
+## src/components/layout/app-header.tsx Template
+
+```tsx
+import { Link } from "react-router-dom";
+import { useTheme } from "next-themes";
+import {
+  Bell,
+  Globe,
+  Moon,
+  Sun,
+  User,
+  Settings,
+  LogOut,
+} from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Avatar, AvatarFallback } from "@/components/ui/avatar";
+import { Badge } from "@/components/ui/badge";
+import { Separator } from "@/components/ui/separator";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+
+interface AppHeaderProps {
+  role: string;
+}
+
+export function AppHeader({ role }: AppHeaderProps) {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <header className="bg-background border-b h-16 flex items-center justify-between px-6 fixed top-0 left-0 right-0 z-30">
+      {/* Left: Logo + App Name */}
+      <div className="flex items-center gap-3">
+        <div className="w-8 h-8 rounded-lg bg-primary flex items-center justify-center">
+          <span className="text-primary-foreground font-bold text-sm">{{APP_INITIALS}}</span>
+        </div>
+        <span className="font-semibold text-lg">{{APP_NAME}}</span>
+      </div>
+
+      {/* Right: Controls */}
+      <div className="flex items-center gap-1">
+        {/* Notification Bell */}
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="ghost" size="icon" className="relative">
+              <Bell className="h-5 w-5" />
+              <Badge
+                variant="destructive"
+                className="absolute -top-1 -right-1 h-4 w-4 p-0 flex items-center justify-center text-[10px]"
+              >
+                3
+              </Badge>
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-80">
+            <DropdownMenuLabel className="flex items-center justify-between">
+              <span>Notifications</span>
+              <Button variant="link" size="sm" className="h-auto p-0 text-xs">
+                Mark all read
+              </Button>
+            </DropdownMenuLabel>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem className="flex flex-col items-start gap-1 py-3">
+              <div className="flex items-center gap-2">
+                <div className="w-2 h-2 rounded-full bg-primary shrink-0" />
+                <span className="font-medium text-sm">New document uploaded</span>
+              </div>
+              <span className="text-xs text-muted-foreground ml-4">
+                A new employment contract has been uploaded for review.
+              </span>
+              <span className="text-xs text-muted-foreground ml-4">2 minutes ago</span>
+            </DropdownMenuItem>
+            <DropdownMenuItem className="flex flex-col items-start gap-1 py-3">
+              <div className="flex items-center gap-2">
+                <div className="w-2 h-2 rounded-full bg-primary shrink-0" />
+                <span className="font-medium text-sm">Status changed</span>
+              </div>
+              <span className="text-xs text-muted-foreground ml-4">
+                Record status has been updated.
+              </span>
+              <span className="text-xs text-muted-foreground ml-4">15 minutes ago</span>
+            </DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem asChild>
+              <Link
+                to={`/${role}/notifications`}
+                className="w-full text-center text-sm font-medium text-primary"
+              >
+                View all notifications
+              </Link>
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+
+        {/* Locale / Globe */}
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="ghost" size="icon">
+              <Globe className="h-5 w-5" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-48">
+            <DropdownMenuLabel>Language</DropdownMenuLabel>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem className="font-medium text-primary">
+              English (EN)
+            </DropdownMenuItem>
+            <DropdownMenuItem>Bahasa Melayu (BM)</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+
+        {/* Dark Mode Toggle */}
+        <Button
+          variant="ghost"
+          size="icon"
+          onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
+        >
+          <Sun className="h-5 w-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
+          <Moon className="absolute h-5 w-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
+        </Button>
+
+        <Separator orientation="vertical" className="h-8 mx-1" />
+
+        {/* User Avatar + Dropdown */}
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="ghost" className="gap-2 px-2">
+              <Avatar className="h-8 w-8">
+                <AvatarFallback className="bg-primary text-primary-foreground text-sm">
+                  U
+                </AvatarFallback>
+              </Avatar>
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-48">
+            <DropdownMenuItem asChild>
+              <Link to={`/${role}/profile`} className="flex items-center gap-2">
+                <User className="h-4 w-4" />
+                Profile
+              </Link>
+            </DropdownMenuItem>
+            <DropdownMenuItem asChild>
+              <Link to={`/${role}/account`} className="flex items-center gap-2">
+                <Settings className="h-4 w-4" />
+                Account
+              </Link>
+            </DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem asChild>
+              {/* Plain <a> — escapes the SPA (basename) to the hub landing page */}
+              <a href="/" className="flex items-center gap-2 text-destructive">
+                <LogOut className="h-4 w-4" />
+                Logout
+              </a>
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
+    </header>
+  );
+}
+```
+
+---
+
+## src/components/layout/app-footer.tsx Template
+
+```tsx
+import { Separator } from "@/components/ui/separator";
+
+export function AppFooter() {
+  return (
+    <>
+      <Separator />
+      <footer className="bg-background px-6 py-3 flex items-center justify-between text-xs text-muted-foreground">
+        <span>&copy; {{COPYRIGHT_YEAR}} {{APP_NAME}}. All rights reserved.</span>
+        <span>{{VERSION}}</span>
+      </footer>
+    </>
+  );
+}
+```
+
+---
+
+## src/components/layout/sidebar-config.ts Template
+
+Export a configuration object defining sidebar navigation items per role. Each item has
+a title, path, and Lucide icon name.
+
+```typescript
+export interface SidebarItem {
+  title: string;
+  path: string;
+  icon: string;
+}
+
+export interface SidebarGroup {
+  label?: string;
+  items: SidebarItem[];
+}
+
+export interface RoleSidebarConfig {
+  label: string;
+  groups: SidebarGroup[];
+  reports?: { title: string; href: string }[];
+}
+
+export const sidebarConfig: Record<string, RoleSidebarConfig> = {
+  "hub-administrator": {
+    label: "Hub Administrator",
+    groups: [
+      {
+        items: [
+          { title: "Home", path: "home", icon: "Home" },
+        ],
+      },
+      {
+        label: "Menu",
+        items: [
+          // { title: "Location Information", path: "location-information", icon: "MapPin" },
+          // { title: "Industrial Classification", path: "industrial-classification", icon: "Tag" },
+          // ... one entry per module for this role
+        ],
+      },
+    ],
+  },
+  // ... repeat for each role
+};
+```
+
+> **Icon mapping**: Use Lucide React icon names matching the module purpose:
+>
+> | Module Pattern | Lucide Icon |
+> |---------------|-------------|
+> | Document / File | `FileText` |
+> | Location / Geography | `MapPin` |
+> | Corridor / Route | `ArrowLeftRight` |
+> | Recruitment / Steps | `ListOrdered` |
+> | Employer / Company | `Building2` |
+> | Classification / Category | `Tag` |
+> | Quota / Allocation | `PieChart` |
+> | Job / Demand | `Briefcase` |
+> | Employee / Person | `Users` |
+> | Settings / Config | `Settings` |
+> | Report | `FileBarChart` |
+
+---
+
+## src/components/layout/app-sidebar.tsx Template
+
+```tsx
+import { Link, useLocation } from "react-router-dom";
+import {
+  Home,
+  MapPin,
+  Tag,
+  Building2,
+  Briefcase,
+  Users,
+  Settings,
+  FileText,
+  ListOrdered,
+  ArrowLeftRight,
+  PieChart,
+  FileBarChart,
+  ChevronsLeft,
+  ChevronsRight,
+} from "lucide-react";
+import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
+import { Separator } from "@/components/ui/separator";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { sidebarConfig } from "./sidebar-config";
+
+const iconMap: Record<string, React.ComponentType<{ className?: string }>> = {
+  Home,
+  MapPin,
+  Tag,
+  Building2,
+  Briefcase,
+  Users,
+  Settings,
+  FileText,
+  ListOrdered,
+  ArrowLeftRight,
+  PieChart,
+  FileBarChart,
+};
+
+interface AppSidebarProps {
+  role: string;
+  collapsed: boolean;
+  onToggle: () => void;
+}
+
+export function AppSidebar({ role, collapsed, onToggle }: AppSidebarProps) {
+  const location = useLocation();
+  const config = sidebarConfig[role];
+
+  if (!config) return null;
+
+  return (
+    <aside
+      className={cn(
+        "bg-background border-r fixed top-16 bottom-0 left-0 overflow-y-auto z-20 transition-all duration-200 flex flex-col",
+        collapsed ? "w-16" : "w-64"
+      )}
+    >
+      <nav className="flex-1 py-4">
+        <TooltipProvider delayDuration={0}>
+          {config.groups.map((group, gi) => (
+            <div key={gi}>
+              {group.label && !collapsed && (
+                <div className="px-4 pt-4 pb-1">
+                  <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
+                    {group.label}
+                  </span>
+                </div>
+              )}
+              {group.label && collapsed && (
+                <Separator className="my-2 mx-2" />
+              )}
+              {group.items.map((item) => {
+                const Icon = iconMap[item.icon] || FileText;
+                const fullPath = `/${role}/${item.path}`;
+                const isActive = location.pathname.startsWith(fullPath);
+
+                const linkContent = (
+                  <Link
+                    to={fullPath}
+                    className={cn(
+                      "flex items-center gap-3 px-4 py-2.5 text-sm transition-colors duration-200",
+                      collapsed && "justify-center px-0",
+                      isActive
+                        ? "bg-primary/5 text-primary border-r-2 border-primary font-medium"
+                        : "text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+                    )}
+                  >
+                    <Icon className="h-5 w-5 shrink-0" />
+                    {!collapsed && <span>{item.title}</span>}
+                  </Link>
+                );
+
+                if (collapsed) {
+                  return (
+                    <Tooltip key={item.path}>
+                      <TooltipTrigger asChild>{linkContent}</TooltipTrigger>
+                      <TooltipContent side="right">{item.title}</TooltipContent>
+                    </Tooltip>
+                  );
+                }
+                return <div key={item.path}>{linkContent}</div>;
+              })}
+            </div>
+          ))}
+
+          {/* Reports section (if applicable) */}
+          {config.reports && config.reports.length > 0 && (
+            <div>
+              {!collapsed && (
+                <div className="px-4 pt-4 pb-1">
+                  <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
+                    Reports
+                  </span>
+                </div>
+              )}
+              {collapsed && <Separator className="my-2 mx-2" />}
+              {config.reports.map((report) => {
+                const linkContent = (
+                  <a
+                    href={report.href}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className={cn(
+                      "flex items-center gap-3 px-4 py-2.5 text-sm text-muted-foreground hover:bg-accent hover:text-accent-foreground transition-colors duration-200",
+                      collapsed && "justify-center px-0"
+                    )}
+                  >
+                    <FileBarChart className="h-5 w-5 shrink-0" />
+                    {!collapsed && <span>{report.title}</span>}
+                  </a>
+                );
+
+                if (collapsed) {
+                  return (
+                    <Tooltip key={report.title}>
+                      <TooltipTrigger asChild>{linkContent}</TooltipTrigger>
+                      <TooltipContent side="right">{report.title}</TooltipContent>
+                    </Tooltip>
+                  );
+                }
+                return <div key={report.title}>{linkContent}</div>;
+              })}
+            </div>
+          )}
+        </TooltipProvider>
+      </nav>
+
+      {/* Collapse toggle */}
+      <div className="p-2 border-t">
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={onToggle}
+          className="w-full"
+        >
+          {collapsed ? (
+            <ChevronsRight className="h-4 w-4" />
+          ) : (
+            <>
+              <ChevronsLeft className="h-4 w-4 mr-2" />
+              <span className="text-xs">Collapse</span>
+            </>
+          )}
+        </Button>
+      </div>
+    </aside>
+  );
+}
+```
+
+---
+
+## Page Component Template
+
+Page components return only content — the layout wrapper (header, sidebar, footer)
+is handled by `AppLayout` via React Router's `<Outlet>`.
+
+```tsx
+// {module-name}.tsx — {Role Display Name}
+// User story traceability: {US_TAG} [{US_VERSION}]
+
+import { useState } from "react";
+import { Link } from "react-router-dom";
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from "@/components/ui/breadcrumb";
+
+// ... other shadcn/ui component imports as needed
+
+export default function PageComponent() {
+  return (
+    <>
+      {/* Breadcrumb */}
+      <div className="px-6 py-3 border-b bg-background">
+        <Breadcrumb>
+          <BreadcrumbList>
+            <BreadcrumbItem>
+              <BreadcrumbLink asChild>
+                <Link to="/{{ROLE}}/home">Home</Link>
+              </BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbPage>{{PAGE_TITLE}}</BreadcrumbPage>
+            </BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+      </div>
+
+      {/* Page Content */}
+      <div className="flex-1 p-6">
+        {/* ... page-specific content ... */}
+      </div>
+    </>
+  );
+}
+```
+
+### Breadcrumb for Sub-pages (detail / edit / create)
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink asChild>
+        <Link to="/{{ROLE}}/home">Home</Link>
+      </BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink asChild>
+        <Link to="/{{ROLE}}/{{MODULE}}">{{MODULE_NAME}}</Link>
+      </BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>{{PAGE_TITLE}}</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+---
+
+## Link Rules Inside Page Components
+
+### Navigation links (within the app)
+
+Use React Router `<Link>` for in-app navigation:
+
+```tsx
+import { Link } from "react-router-dom";
+
+<Link
+  to="/{{ROLE}}/{{TARGET_PAGE}}"
+  className="..."
+>
+  View Details
+</Link>
+```
+
+### Image links — MUST open in new tab
+
+```tsx
+<a href="https://placehold.co/800x600" target="_blank" rel="noopener noreferrer">
+  View Image
+</a>
+```
+
+### PDF / document links — MUST open in new tab
+
+```tsx
+import { FileText } from "lucide-react";
+
+<a href="/reports/sample.pdf" target="_blank" rel="noopener noreferrer" className="flex items-center gap-2">
+  <FileText className="h-4 w-4" />
+  View PDF
+</a>
+```
+
+### Action buttons in tables
+
+```tsx
+import { Link } from "react-router-dom";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+
+{/* View / Details → React Router Link */}
+<Button variant="outline" size="sm" asChild>
+  <Link to="/{{ROLE}}/{{MODULE}}-detail">View</Link>
+</Button>
+
+{/* Edit → React Router Link */}
+<Button variant="outline" size="sm" asChild>
+  <Link to="/{{ROLE}}/{{MODULE}}-edit">Edit</Link>
+</Button>
+
+{/* Delete → shadcn/ui Dialog */}
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="outline" size="sm" className="text-destructive border-destructive/50">
+      Delete
+    </Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Delete Record</DialogTitle>
+      <DialogDescription>
+        Are you sure you want to delete this record? This action cannot be undone.
+      </DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <Button variant="outline">Cancel</Button>
+      <Button variant="destructive">Delete</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+
+{/* Add New → React Router Link */}
+<Button asChild>
+  <Link to="/{{ROLE}}/{{MODULE}}-create">
+    + Add New
+  </Link>
+</Button>
+```
+
+### Tab navigation in detail pages
+
+Use shadcn/ui `<Tabs>` for inline tabs:
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+
+<Tabs defaultValue="overview">
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="documents">Documents</TabsTrigger>
+    <TabsTrigger value="history">History</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview">
+    {/* Overview content */}
+  </TabsContent>
+  <TabsContent value="documents">
+    {/* Documents content */}
+  </TabsContent>
+  <TabsContent value="history">
+    {/* History content */}
+  </TabsContent>
+</Tabs>
+```
+
+If tabs are separate page files, use `<Link>` instead:
+
+```tsx
+import { Link, useLocation } from "react-router-dom";
+import { cn } from "@/lib/utils";
+
+const tabs = [
+  { label: "Overview", path: "/{{ROLE}}/{{MODULE}}-tab-overview" },
+  { label: "Documents", path: "/{{ROLE}}/{{MODULE}}-tab-documents" },
+  { label: "History", path: "/{{ROLE}}/{{MODULE}}-tab-history" },
+];
+
+const location = useLocation();
+
+<div className="flex border-b mb-6">
+  {tabs.map((tab) => (
+    <Link
+      key={tab.path}
+      to={tab.path}
+      className={cn(
+        "px-4 py-2 text-sm font-medium border-b-2 -mb-px transition-colors",
+        location.pathname === tab.path
+          ? "border-primary text-primary"
+          : "border-transparent text-muted-foreground hover:text-foreground"
+      )}
+    >
+      {tab.label}
+    </Link>
+  ))}
+</div>
+```
+
+### Back / Cancel buttons
+
+```tsx
+import { Link } from "react-router-dom";
+import { Button } from "@/components/ui/button";
+import { ArrowLeft } from "lucide-react";
+
+<Button variant="outline" asChild>
+  <Link to="/{{ROLE}}/{{PARENT_MODULE}}">
+    <ArrowLeft className="h-4 w-4 mr-2" />
+    Back to List
+  </Link>
+</Button>
+```
+
+### Pagination
+
+```tsx
+import { useState } from "react";
+import { Button } from "@/components/ui/button";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from "@/components/ui/pagination";
+
+const [currentPage, setCurrentPage] = useState(1);
+const [pageSize, setPageSize] = useState(10);
+const totalItems = 47;
+const totalPages = Math.ceil(totalItems / pageSize);
+
+<div className="flex items-center justify-between mt-4">
+  <span className="text-sm text-muted-foreground">
+    Showing {(currentPage - 1) * pageSize + 1}–{Math.min(currentPage * pageSize, totalItems)} of {totalItems} results
+  </span>
+
+  <Pagination>
+    <PaginationContent>
+      <PaginationItem>
+        <PaginationPrevious
+          onClick={() => setCurrentPage(Math.max(1, currentPage - 1))}
+          className={currentPage === 1 ? "pointer-events-none opacity-50" : "cursor-pointer"}
+        />
+      </PaginationItem>
+      {/* Page numbers — generate dynamically */}
+      <PaginationItem>
+        <PaginationLink
+          isActive={currentPage === 1}
+          onClick={() => setCurrentPage(1)}
+          className="cursor-pointer"
+        >
+          1
+        </PaginationLink>
+      </PaginationItem>
+      {currentPage > 3 && (
+        <PaginationItem>
+          <PaginationEllipsis />
+        </PaginationItem>
+      )}
+      {/* ... middle pages ... */}
+      <PaginationItem>
+        <PaginationNext
+          onClick={() => setCurrentPage(Math.min(totalPages, currentPage + 1))}
+          className={currentPage === totalPages ? "pointer-events-none opacity-50" : "cursor-pointer"}
+        />
+      </PaginationItem>
+    </PaginationContent>
+  </Pagination>
+
+  <Select value={String(pageSize)} onValueChange={(v) => { setPageSize(Number(v)); setCurrentPage(1); }}>
+    <SelectTrigger className="w-20">
+      <SelectValue />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="10">10</SelectItem>
+      <SelectItem value="25">25</SelectItem>
+      <SelectItem value="50">50</SelectItem>
+    </SelectContent>
+  </Select>
+</div>
+```
+
+---
+
+## Common Pages Content
+
+### home.tsx page component
+
+```tsx
+import { Link } from "react-router-dom";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table";
+import { Badge } from "@/components/ui/badge";
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbList,
+  BreadcrumbPage,
+} from "@/components/ui/breadcrumb";
+
+export default function Home() {
+  return (
+    <>
+      <div className="px-6 py-3 border-b bg-background">
+        <Breadcrumb>
+          <BreadcrumbList>
+            <BreadcrumbItem>
+              <BreadcrumbPage>Home</BreadcrumbPage>
+            </BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+      </div>
+      <div className="flex-1 p-6">
+        <h1 className="text-2xl font-bold mb-2">Welcome back</h1>
+        <p className="text-muted-foreground mb-6">{{APP_NAME}} — {{ROLE_DISPLAY}}</p>
+
+        {/* Summary stat cards — one per module */}
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 mb-8">
+          {/* Repeat: one Card per module */}
+          <Card>
+            <CardHeader className="pb-2">
+              <CardTitle className="text-sm font-medium text-muted-foreground">
+                Module Name
+              </CardTitle>
+            </CardHeader>
+            <CardContent>
+              <div className="text-2xl font-bold">142</div>
+              <p className="text-xs text-muted-foreground">+12 this week</p>
+            </CardContent>
+          </Card>
+        </div>
+
+        {/* Recent activity table */}
+        <Card>
+          <CardHeader>
+            <CardTitle>Recent Activity</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Table>
+              <TableHeader>
+                <TableRow>
+                  <TableHead>Action</TableHead>
+                  <TableHead>Module</TableHead>
+                  <TableHead>User</TableHead>
+                  <TableHead>Date</TableHead>
+                </TableRow>
+              </TableHeader>
+              <TableBody>
+                <TableRow>
+                  <TableCell><Badge>Created</Badge></TableCell>
+                  <TableCell>Module Name</TableCell>
+                  <TableCell>John Doe</TableCell>
+                  <TableCell>15 Aug 2025 10:30</TableCell>
+                </TableRow>
+              </TableBody>
+            </Table>
+          </CardContent>
+        </Card>
+      </div>
+    </>
+  );
+}
+```
+
+### profile.tsx page component
+
+User profile: `<Avatar>`, full name, email, role `<Badge>`, personal info `<Card>` (read-only),
+Edit `<Button>`.
+
+### account.tsx page component
+
+Account settings: Change Password `<Card>` form, Notification Preferences `<Card>` with
+`<Switch>` toggles, Language/Locale `<Select>`, Session Management `<Card>` with `<Table>`.
+
+### notifications.tsx page component
+
+Notifications list: shadcn/ui `<Tabs>` for All/Unread/Read filter, notification `<Card>` items
+with Lucide icon / title / message / timestamp / read-unread dot, Mark all as read `<Button>`,
+`<Pagination>` (MANDATORY).
+
+---
+
+## Quick-Start Instructions (append to output summary)
+
+```
+Quick Start
+===========
+1. cd {mockup folder} && npm install && npm run build   (one-time build for the hub)
+2. cd <root>/mockup
+3. npm start          (zero dependencies — no npm install required)
+4. Open http://localhost:3000 in your browser
+   - Landing page lists ALL applications and roles
+   - This app's screen index: http://localhost:3000/{app_slug}
+5. Change port: PORT=4000 npm start, or edit <root>/mockup/mockup.config.json
+
+Design iteration (optional): cd {mockup folder} && npm run dev
+→ http://localhost:5173/{app_slug}/
+```