create-lego-one 2.0.12 → 2.0.13

package/template/docs/framework/plans/03-host-kernel.md

@@ -0,0 +1,1518 @@
+# Host Kernel Implementation Plan
+
+> **For AI Implementing This Plan:** This is document 03 of 13. Complete `01-infrastructure-setup.md` and `02-pocketbase-setup.md` first.
+
+**Goal:** Initialize the Modern.js host application (the "Kernel") with shared state, layout, routing, Garfish configuration, and base providers.
+
+**Architecture:** Host app is the kernel that provides authentication, multitenancy, RBAC, shared services, and layout structure. Plugins are loaded dynamically as sub-apps via Garfish.
+
+**Tech Stack:** Modern.js, Rspack, Garfish, React 18, TypeScript, Zustand, TanStack Query v5, Tailwind CSS, PocketBase
+
+---
+
+## Prerequisites
+
+- ✅ Completed `01-infrastructure-setup.md`
+- ✅ Completed `02-pocketbase-setup.md`
+- ✅ pnpm workspace configured
+- ✅ PocketBase collections and migrations in place
+
+---
+
+## Task 1: Initialize Modern.js Host App
+
+**Files:**
+- Create: `host/package.json`
+- Create: `host/tsconfig.json`
+- Create: `host/modern.config.ts`
+- Create: `host/.gitignore`
+
+### Step 1: Create host package.json
+
+**File:** `host/package.json`
+
+```json
+{
+  "name": "host",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "modern dev",
+    "build": "modern build",
+    "start": "modern start",
+    "lint": "eslint src --ext .ts,.tsx",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@garfish/hooks": "^1.22.0",
+    "@modern-js/runtime": "^2.60.0",
+    "@modern-js/runtime/garfish": "^2.60.0",
+    "@radix-ui/react-dropdown-menu": "^2.1.2",
+    "@radix-ui/react-slot": "^1.1.0",
+    "@tanstack/react-query": "^5.59.0",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.1",
+    "garfish": "^1.22.0",
+    "lucide-react": "^0.454.0",
+    "pocketbase": "^0.21.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tailwind-merge": "^2.5.4",
+    "tailwindcss-animate": "^1.0.7",
+    "zustand": "^5.0.1"
+  },
+  "devDependencies": {
+    "@modern-js/app-tools": "^2.60.0",
+    "@modern-js/plugin-garfish": "^2.60.0",
+    "@modern-js/tsconfig": "^2.60.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.15",
+    "typescript": "^5.6.3"
+  }
+}
+```
+
+### Step 2: Create host tsconfig.json
+
+**File:** `host/tsconfig.json`
+
+```json
+{
+  "extends": "@modern-js/tsconfig/base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "paths": {
+      "@/*": ["./src/*"],
+      "@lego/kernel/*": ["./src/kernel/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### Step 3: Create host modern.config.ts
+
+**File:** `host/modern.config.ts`
+
+```typescript
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { garfishPlugin } from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  // Enable Rspack for high-performance builds
+  tools: {
+    rspack: (config) => {
+      return config;
+    },
+  },
+
+  // Enable file-based routing for the host kernel
+  runtime: {
+    router: true,
+  },
+
+  // Register Garfish plugin for micro-frontend capabilities
+  plugins: [appTools(), garfishPlugin()],
+});
+```
+
+### Step 4: Create host .gitignore
+
+**File:** `host/.gitignore`
+
+```
+node_modules/
+dist/
+.modern/
+*.local
+.DS_Store
+```
+
+### Step 5: Install host dependencies
+
+**Run:** From root directory
+
+```bash
+pnpm install
+```
+
+Expected: All dependencies installed successfully.
+
+---
+
+## Task 2: Configure Tailwind CSS for Modern.js
+
+**Files:**
+- Create: `host/tailwind.config.ts`
+- Create: `host/postcss.config.js`
+- Create: `host/src/global.css`
+- Create: `host/src/App.tsx`
+
+### Step 1: Create Tailwind config
+
+**File:** `host/tailwind.config.ts`
+
+```typescript
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
+  darkMode: ['class'],
+  content: [
+    './src/**/*.{js,ts,jsx,tsx,mdx}',
+    '../../packages/plugins/@lego/*/src/**/*.{js,ts,jsx,tsx,mdx}',
+  ],
+  theme: {
+    container: {
+      center: true,
+      padding: '2rem',
+      screens: {
+        '2xl': '1400px',
+      },
+    },
+    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)',
+      },
+      keyframes: {
+        'accordion-down': {
+          from: { height: '0' },
+          to: { height: 'var(--radix-accordion-content-height)' },
+        },
+        'accordion-up': {
+          from: { height: 'var(--radix-accordion-content-height)' },
+          to: { height: '0' },
+        },
+      },
+      animation: {
+        'accordion-down': 'accordion-down 0.2s ease-out',
+        'accordion-up': 'accordion-up 0.2s ease-out',
+      },
+    },
+  },
+  plugins: [require('tailwindcss-animate')],
+};
+
+export default config;
+```
+
+### Step 2: Create PostCSS config
+
+**File:** `host/postcss.config.js`
+
+```javascript
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+```
+
+### Step 3: Create global CSS with CSS variables
+
+**File:** `host/src/global.css`
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 222.2 84% 4.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 222.2 84% 4.9%;
+    --primary: 221.2 83.2% 53.3%;
+    --primary-foreground: 210 40% 98%;
+    --secondary: 210 40% 96.1%;
+    --secondary-foreground: 222.2 47.4% 11.2%;
+    --muted: 210 40% 96.1%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+    --accent: 210 40% 96.1%;
+    --accent-foreground: 222.2 47.4% 11.2%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 214.3 31.8% 91.4%;
+    --input: 214.3 31.8% 91.4%;
+    --ring: 221.2 83.2% 53.3%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    --card: 222.2 84% 4.9%;
+    --card-foreground: 210 40% 98%;
+    --popover: 222.2 84% 4.9%;
+    --popover-foreground: 210 40% 98%;
+    --primary: 217.2 91.2% 59.8%;
+    --primary-foreground: 222.2 47.4% 11.2%;
+    --secondary: 217.2 32.6% 17.5%;
+    --secondary-foreground: 210 40% 98%;
+    --muted: 217.2 32.6% 17.5%;
+    --muted-foreground: 215 20.2% 65.1%;
+    --accent: 217.2 32.6% 17.5%;
+    --accent-foreground: 210 40% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 217.2 32.6% 17.5%;
+    --input: 217.2 32.6% 17.5%;
+    --ring: 224.3 76.3% 48%;
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+```
+
+### Step 4: Create root App component
+
+**File:** `host/src/App.tsx`
+
+```typescript
+import { Outlet } from '@modern-js/runtime/router';
+import './global.css';
+
+export default function App() {
+  return <Outlet />;
+}
+```
+
+---
+
+## Task 3: Create Shared State Bridge
+
+**Files:**
+- Create: `host/src/kernel/shared-state/types.ts`
+- Create: `host/src/kernel/shared-state/store.ts`
+- Create: `host/src/kernel/shared-state/bridge.ts`
+- Create: `host/src/kernel/shared-state/index.ts`
+
+### Step 1: Create shared state types
+
+**File:** `host/src/kernel/shared-state/types.ts`
+
+```typescript
+import type { RecordAuth } from 'pocketbase';
+
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  avatar?: string;
+}
+
+export interface Organization {
+  id: string;
+  name: string;
+  slug: string;
+}
+
+export interface AuthState {
+  user: User | null;
+  token: string | null;
+  isAuthenticated: boolean;
+  organization: Organization | null;
+}
+
+export type Theme = 'light' | 'dark' | 'system';
+
+export interface UIState {
+  theme: Theme;
+  sidebarOpen: boolean;
+  mobileMenuOpen: boolean;
+}
+
+export interface Toast {
+  id: string;
+  title: string;
+  description?: string;
+  variant?: 'default' | 'destructive' | 'success';
+}
+
+export interface GlobalKernelState extends AuthState, UIState {
+  // Auth actions
+  setUser: (user: User | null) => void;
+  setToken: (token: string | null) => void;
+  setOrganization: (org: Organization | null) => void;
+  clearAuth: () => void;
+
+  // UI actions
+  setTheme: (theme: Theme) => void;
+  toggleSidebar: () => void;
+  setSidebarOpen: (open: boolean) => void;
+  toggleMobileMenu: () => void;
+  setMobileMenuOpen: (open: boolean) => void;
+
+  // Toast actions
+  toasts: Toast[];
+  addToast: (toast: Omit<Toast, 'id'>) => void;
+  removeToast: (id: string) => void;
+
+  // Loading state
+  isLoading: boolean;
+  setIsLoading: (loading: boolean) => void;
+}
+```
+
+### Step 2: Create Zustand store
+
+**File:** `host/src/kernel/shared-state/store.ts`
+
+```typescript
+import { create } from 'zustand';
+import { devtools, persist } from 'zustand/middleware';
+import type { GlobalKernelState, Theme, User, Organization, Toast } from './types';
+
+const generateId = () => Math.random().toString(36).substring(2, 9);
+
+export const useGlobalKernelState = create<GlobalKernelState>()(
+  devtools(
+    persist(
+      (set) => ({
+        // Initial state
+        user: null,
+        token: null,
+        isAuthenticated: false,
+        organization: null,
+        theme: 'system',
+        sidebarOpen: true,
+        mobileMenuOpen: false,
+        toasts: [],
+        isLoading: false,
+
+        // Auth actions
+        setUser: (user: User | null) => set({ user, isAuthenticated: !!user }),
+        setToken: (token: string | null) => set({ token }),
+        setOrganization: (org: Organization | null) => set({ organization: org }),
+        clearAuth: () => set({
+          user: null,
+          token: null,
+          isAuthenticated: false,
+          organization: null,
+        }),
+
+        // UI actions
+        setTheme: (theme: Theme) => set({ theme }),
+        toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
+        setSidebarOpen: (open: boolean) => set({ sidebarOpen: open }),
+        toggleMobileMenu: () => set((state) => ({ mobileMenuOpen: !state.mobileMenuOpen })),
+        setMobileMenuOpen: (open: boolean) => set({ mobileMenuOpen: open }),
+
+        // Toast actions
+        addToast: (toast: Omit<Toast, 'id'>) => set((state) => ({
+          toasts: [...state.toasts, { ...toast, id: generateId() }],
+        })),
+        removeToast: (id: string) => set((state) => ({
+          toasts: state.toasts.filter((t) => t.id !== id),
+        })),
+
+        // Loading actions
+        setIsLoading: (isLoading: boolean) => set({ isLoading }),
+      }),
+      {
+        name: 'lego-kernel-state',
+        partialize: (state) => ({
+          theme: state.theme,
+          sidebarOpen: state.sidebarOpen,
+          token: state.token,
+        }),
+      }
+    ),
+    { name: 'LegoKernelState' }
+  )
+);
+```
+
+### Step 3: Create window bridge for plugins
+
+**File:** `host/src/kernel/shared-state/bridge.ts`
+
+```typescript
+import { useGlobalKernelState } from './store';
+
+// Declare window type for shared state
+declare global {
+  interface Window {
+    __LEGO_KERNEL_STATE__?: {
+      useGlobalKernelState: typeof useGlobalKernelState;
+    };
+  }
+}
+
+// Register shared state to window for plugin access
+export function registerSharedState() {
+  if (typeof window !== 'undefined') {
+    window.__LEGO_KERNEL_STATE__ = {
+      useGlobalKernelState,
+    };
+  }
+}
+
+// Hook for plugins to access kernel state
+export function useKernelState() {
+  return useGlobalKernelState;
+}
+```
+
+### Step 4: Create barrel export
+
+**File:** `host/src/kernel/shared-state/index.ts`
+
+```typescript
+export * from './types';
+export * from './store';
+export * from './bridge';
+```
+
+---
+
+## Task 4: Create Base Providers
+
+**Files:**
+- Create: `host/src/kernel/providers/PocketBaseProvider.tsx`
+- Create: `host/src/kernel/providers/QueryProvider.tsx`
+- Create: `host/src/kernel/providers/ThemeProvider.tsx`
+- Create: `host/src/kernel/providers/index.ts`
+
+### Step 1: Create PocketBase provider
+
+**File:** `host/src/kernel/providers/PocketBaseProvider.tsx`
+
+```typescript
+import { createContext, useContext, useEffect, useState } from 'react';
+import PocketBase from 'pocketbase';
+import { useGlobalKernelState } from '../shared-state';
+
+const PocketBaseContext = createContext<PocketBase | null>(null);
+
+export function PocketBaseProvider({ children }: { children: React.ReactNode }) {
+  const [pb, setPb] = useState<PocketBase | null>(null);
+  const { token, clearAuth } = useGlobalKernelState();
+
+  useEffect(() => {
+    // Initialize PocketBase client
+    const client = new PocketBase(import.meta.env.VITE_POCKETBASE_URL || 'http://127.0.0.1:8090');
+
+    // Load stored token
+    const storedToken = localStorage.getItem('pocketbase_auth');
+    if (storedToken) {
+      client.authStore.save(storedToken, null);
+    }
+
+    setPb(client);
+
+    // Set up auth cleanup on token invalidation
+    client.authStore.onChange((token, model) => {
+      if (!token) {
+        clearAuth();
+        localStorage.removeItem('pocketbase_auth');
+      } else {
+        localStorage.setItem('pocketbase_auth', token);
+      }
+    });
+
+    return () => {
+      // Cleanup on unmount
+    };
+  }, [clearAuth]);
+
+  // Update auth store when token changes in state
+  useEffect(() => {
+    if (pb && token && pb.authStore.token !== token) {
+      pb.authStore.save(token, null);
+    }
+  }, [pb, token]);
+
+  if (!pb) {
+    return null; // or a loading spinner
+  }
+
+  return (
+    <PocketBaseContext.Provider value={pb}>
+      {children}
+    </PocketBaseContext.Provider>
+  );
+}
+
+export function usePocketBase() {
+  const context = useContext(PocketBaseContext);
+  if (!context) {
+    throw new Error('usePocketBase must be used within PocketBaseProvider');
+  }
+  return context;
+}
+```
+
+### Step 2: Create TanStack Query provider
+
+**File:** `host/src/kernel/providers/QueryProvider.tsx`
+
+```typescript
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import { useState, type ReactNode } from 'react';
+
+export function QueryProvider({ children }: { children: ReactNode }) {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            staleTime: 1000 * 60 * 5, // 5 minutes
+            gcTime: 1000 * 60 * 30, // 30 minutes (formerly cacheTime)
+            retry: 1,
+            refetchOnWindowFocus: false,
+          },
+        },
+      })
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      {import.meta.env.MODE === 'development' && (
+        <ReactQueryDevtools initialIsOpen={false} />
+      )}
+    </QueryClientProvider>
+  );
+}
+```
+
+### Step 3: Create theme provider
+
+**File:** `host/src/kernel/providers/ThemeProvider.tsx`
+
+```typescript
+import { useEffect } from 'react';
+import { useGlobalKernelState, type Theme } from '../shared-state';
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const { theme } = useGlobalKernelState();
+
+  useEffect(() => {
+    const root = window.document.documentElement;
+    root.classList.remove('light', 'dark');
+
+    let effectiveTheme: 'light' | 'dark' = 'light';
+
+    if (theme === 'system') {
+      effectiveTheme = window.matchMedia('(prefers-color-scheme: dark)').matches
+        ? 'dark'
+        : 'light';
+    } else {
+      effectiveTheme = theme;
+    }
+
+    root.classList.add(effectiveTheme);
+  }, [theme]);
+
+  return <>{children}</>;
+}
+```
+
+### Step 4: Create barrel export
+
+**File:** `host/src/kernel/providers/index.ts`
+
+```typescript
+export * from './PocketBaseProvider';
+export * from './QueryProvider';
+export * from './ThemeProvider';
+```
+
+---
+
+## Task 5: Create UI Utilities
+
+**Files:**
+- Create: `host/src/kernel/lib/utils.ts`
+- Create: `host/src/kernel/lib/cn.ts`
+
+### Step 1: Create utility functions
+
+**File:** `host/src/kernel/lib/utils.ts`
+
+```typescript
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+export function getInitials(name: string): string {
+  return name
+    .split(' ')
+    .map((n) => n[0])
+    .join('')
+    .toUpperCase()
+    .slice(0, 2);
+}
+
+export function formatDate(date: string | Date): string {
+  return new Intl.DateTimeFormat('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  }).format(new Date(date));
+}
+
+export function formatRelativeTime(date: string | Date): string {
+  const now = new Date();
+  const past = new Date(date);
+  const diffInSeconds = Math.floor((now.getTime() - past.getTime()) / 1000);
+
+  if (diffInSeconds < 60) return 'just now';
+  if (diffInSeconds < 3600) return `${Math.floor(diffInSeconds / 60)}m ago`;
+  if (diffInSeconds < 86400) return `${Math.floor(diffInSeconds / 3600)}h ago`;
+  if (diffInSeconds < 604800) return `${Math.floor(diffInSeconds / 86400)}d ago`;
+
+  return formatDate(date);
+}
+```
+
+### Step 2: Create barrel export
+
+**File:** `host/src/kernel/lib/cn.ts`
+
+```typescript
+export { cn } from './utils';
+```
+
+---
+
+## Task 6: Create Host Layout Structure
+
+**Files:**
+- Create: `host/src/layout/Shell.tsx`
+- Create: `host/src/layout/Sidebar.tsx`
+- Create: `host/src/layout/Topbar.tsx`
+- Create: `host/src/layout/MobileMenu.tsx`
+- Create: `host/src/layout/index.ts`
+
+### Step 1: Create shell layout component
+
+**File:** `host/src/layout/Shell.tsx`
+
+```typescript
+import { Outlet } from '@modern-js/runtime/router';
+import { Sidebar } from './Sidebar';
+import { Topbar } from './Topbar';
+import { MobileMenu } from './MobileMenu';
+import { useGlobalKernelState } from '../kernel/shared-state';
+
+export function Shell() {
+  const { sidebarOpen, mobileMenuOpen } = useGlobalKernelState();
+
+  return (
+    <div className="min-h-screen bg-background">
+      {/* Mobile menu overlay */}
+      {mobileMenuOpen && (
+        <div
+          className="fixed inset-0 z-40 bg-background/80 backdrop-blur-sm lg:hidden"
+          aria-hidden="true"
+        />
+      )}
+
+      {/* Sidebar */}
+      <Sidebar />
+
+      {/* Main content area */}
+      <div
+        className={`transition-all duration-300 lg:pl-64 ${
+          sidebarOpen ? 'lg:pl-64' : 'lg:pl-16'
+        }`}
+      >
+        {/* Topbar */}
+        <Topbar />
+
+        {/* Page content */}
+        <main className="min-h-[calc(100vh-4rem)] p-6">
+          <Outlet />
+        </main>
+      </div>
+
+      {/* Mobile menu */}
+      <MobileMenu />
+    </div>
+  );
+}
+```
+
+### Step 2: Create sidebar component
+
+**File:** `host/src/layout/Sidebar.tsx`
+
+```typescript
+import { Link, NavLink } from '@modern-js/runtime/router';
+import { useGlobalKernelState } from '../kernel/shared-state';
+import {
+  Home,
+  LayoutDashboard,
+  Settings,
+  ChevronLeft,
+  ChevronRight,
+  CheckSquare,
+} from 'lucide-react';
+import { cn } from '../kernel/lib/utils';
+
+const navItems = [
+  { to: '/', icon: Home, label: 'Home' },
+  { to: '/dashboard', icon: LayoutDashboard, label: 'Dashboard' },
+  { to: '/todos', icon: CheckSquare, label: 'Todos' },
+];
+
+export function Sidebar() {
+  const { sidebarOpen, toggleSidebar, mobileMenuOpen } = useGlobalKernelState();
+
+  return (
+    <>
+      {/* Mobile sidebar */}
+      <aside
+        className={cn(
+          'fixed inset-y-0 left-0 z-50 w-64 transform border-r bg-card transition-transform duration-300 lg:hidden',
+          mobileMenuOpen ? 'translate-x-0' : '-translate-x-full'
+        )}
+      >
+        <div className="flex h-16 items-center justify-between border-b px-6">
+          <Link to="/" className="flex items-center gap-2 font-semibold">
+            <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-primary text-primary-foreground">
+              L
+            </div>
+            <span>Lego-One</span>
+          </Link>
+        </div>
+
+        <nav className="space-y-1 p-4">
+          {navItems.map((item) => (
+            <NavLink
+              key={item.to}
+              to={item.to}
+              end={item.to === '/'}
+              className={({ isActive }) =>
+                cn(
+                  'flex items-center gap-3 rounded-lg px-3 py-2 text-sm font-medium transition-colors',
+                  isActive
+                    ? 'bg-primary text-primary-foreground'
+                    : 'text-muted-foreground hover:bg-muted hover:text-foreground'
+                )
+              }
+            >
+              <item.icon className="h-5 w-5" />
+              {item.label}
+            </NavLink>
+          ))}
+        </nav>
+
+        <div className="absolute bottom-0 left-0 right-0 border-t p-4">
+          <NavLink
+            to="/settings"
+            className={({ isActive }) =>
+              cn(
+                'flex items-center gap-3 rounded-lg px-3 py-2 text-sm font-medium transition-colors',
+                isActive
+                  ? 'bg-primary text-primary-foreground'
+                  : 'text-muted-foreground hover:bg-muted hover:text-foreground'
+              )
+            }
+          >
+            <Settings className="h-5 w-5" />
+            Settings
+          </NavLink>
+        </div>
+      </aside>
+
+      {/* Desktop sidebar */}
+      <aside
+        className={cn(
+          'fixed inset-y-0 left-0 z-30 hidden border-r bg-card transition-all duration-300 lg:block',
+          sidebarOpen ? 'w-64' : 'w-16'
+        )}
+      >
+        <div className="flex h-16 items-center justify-between border-b px-4">
+          {sidebarOpen ? (
+            <Link to="/" className="flex items-center gap-2 font-semibold">
+              <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-primary text-primary-foreground">
+                L
+              </div>
+              <span>Lego-One</span>
+            </Link>
+          ) : (
+            <Link to="/" className="flex items-center justify-center">
+              <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-primary text-primary-foreground">
+                L
+              </div>
+            </Link>
+          )}
+
+          <button
+            onClick={toggleSidebar}
+            className="rounded-lg p-1.5 text-muted-foreground hover:bg-muted hover:text-foreground"
+          >
+            {sidebarOpen ? (
+              <ChevronLeft className="h-5 w-5" />
+            ) : (
+              <ChevronRight className="h-5 w-5" />
+            )}
+          </button>
+        </div>
+
+        <nav className="space-y-1 p-2">
+          {navItems.map((item) => (
+            <NavLink
+              key={item.to}
+              to={item.to}
+              end={item.to === '/'}
+              className={({ isActive }) =>
+                cn(
+                  'flex items-center gap-3 rounded-lg px-3 py-2 text-sm font-medium transition-colors',
+                  !sidebarOpen && 'justify-center',
+                  isActive
+                    ? 'bg-primary text-primary-foreground'
+                    : 'text-muted-foreground hover:bg-muted hover:text-foreground'
+                )
+              }
+              title={!sidebarOpen ? item.label : undefined}
+            >
+              <item.icon className="h-5 w-5 flex-shrink-0" />
+              {sidebarOpen && <span>{item.label}</span>}
+            </NavLink>
+          ))}
+        </nav>
+
+        <div className="absolute bottom-0 left-0 right-0 border-t p-2">
+          <NavLink
+            to="/settings"
+            className={({ isActive }) =>
+              cn(
+                'flex items-center gap-3 rounded-lg px-3 py-2 text-sm font-medium transition-colors',
+                !sidebarOpen && 'justify-center',
+                isActive
+                  ? 'bg-primary text-primary-foreground'
+                  : 'text-muted-foreground hover:bg-muted hover:text-foreground'
+              )
+            }
+            title={!sidebarOpen ? 'Settings' : undefined}
+          >
+            <Settings className="h-5 w-5 flex-shrink-0" />
+            {sidebarOpen && <span>Settings</span>}
+          </NavLink>
+        </div>
+      </aside>
+    </>
+  );
+}
+```
+
+### Step 3: Create topbar component
+
+**File:** `host/src/layout/Topbar.tsx`
+
+```typescript
+import { useGlobalKernelState } from '../kernel/shared-state';
+import { Menu, Bell, User } from 'lucide-react';
+import { Link } from '@modern-js/runtime/router';
+import { getInitials } from '../kernel/lib/utils';
+
+export function Topbar() {
+  const { toggleMobileMenu, user } = useGlobalKernelState();
+
+  return (
+    <header className="sticky top-0 z-20 flex h-16 items-center gap-4 border-b bg-background px-6">
+      {/* Mobile menu button */}
+      <button
+        onClick={toggleMobileMenu}
+        className="lg:hidden rounded-lg p-2 text-muted-foreground hover:bg-muted"
+      >
+        <Menu className="h-5 w-5" />
+      </button>
+
+      {/* Breadcrumb/spacer */}
+      <div className="flex-1" />
+
+      {/* Actions */}
+      <div className="flex items-center gap-2">
+        <button className="rounded-lg p-2 text-muted-foreground hover:bg-muted">
+          <Bell className="h-5 w-5" />
+        </button>
+
+        {user ? (
+          <Link
+            to="/settings/profile"
+            className="flex h-9 w-9 items-center justify-center rounded-full bg-primary text-primary-foreground text-sm font-medium"
+          >
+            {getInitials(user.name)}
+          </Link>
+        ) : (
+          <div className="flex h-9 w-9 items-center justify-center rounded-full bg-muted text-muted-foreground">
+            <User className="h-5 w-5" />
+          </div>
+        )}
+      </div>
+    </header>
+  );
+}
+```
+
+### Step 4: Create mobile menu component
+
+**File:** `host/src/layout/MobileMenu.tsx`
+
+```typescript
+import { NavLink } from '@modern-js/runtime/router';
+import { useGlobalKernelState } from '../kernel/shared-state';
+import {
+  Home,
+  LayoutDashboard,
+  Settings,
+  CheckSquare,
+  X,
+} from 'lucide-react';
+import { cn } from '../kernel/lib/utils';
+
+const navItems = [
+  { to: '/', icon: Home, label: 'Home' },
+  { to: '/dashboard', icon: LayoutDashboard, label: 'Dashboard' },
+  { to: '/todos', icon: CheckSquare, label: 'Todos' },
+  { to: '/settings', icon: Settings, label: 'Settings' },
+];
+
+export function MobileMenu() {
+  const { mobileMenuOpen, setMobileMenuOpen } = useGlobalKernelState();
+
+  if (!mobileMenuOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 lg:hidden">
+      <div className="fixed inset-y-0 right-0 w-64 border-l bg-background p-6 shadow-lg">
+        <div className="flex items-center justify-between mb-8">
+          <h2 className="text-lg font-semibold">Menu</h2>
+          <button
+            onClick={() => setMobileMenuOpen(false)}
+            className="rounded-lg p-2 text-muted-foreground hover:bg-muted"
+          >
+            <X className="h-5 w-5" />
+          </button>
+        </div>
+
+        <nav className="space-y-1">
+          {navItems.map((item) => (
+            <NavLink
+              key={item.to}
+              to={item.to}
+              end={item.to === '/'}
+              onClick={() => setMobileMenuOpen(false)}
+              className={({ isActive }) =>
+                cn(
+                  'flex items-center gap-3 rounded-lg px-3 py-2 text-sm font-medium transition-colors',
+                  isActive
+                    ? 'bg-primary text-primary-foreground'
+                    : 'text-muted-foreground hover:bg-muted hover:text-foreground'
+                )
+              }
+            >
+              <item.icon className="h-5 w-5" />
+              {item.label}
+            </NavLink>
+          ))}
+        </nav>
+      </div>
+    </div>
+  );
+}
+```
+
+### Step 5: Create barrel export
+
+**File:** `host/src/layout/index.ts`
+
+```typescript
+export * from './Shell';
+export * from './Sidebar';
+export * from './Topbar';
+export * from './MobileMenu';
+```
+
+---
+
+## Task 7: Configure Garfish and Create Plugin Routes
+
+**Files:**
+- Create: `host/src/modern.runtime.ts`
+- Create: `host/src/routes/_.tsx`
+- Create: `host/src/routes/index.tsx`
+- Create: `host/src/routes/dashboard._.tsx`
+
+### Step 1: Create Modern.js runtime config
+
+**File:** `host/src/modern.runtime.ts`
+
+```typescript
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+// Development vs Production configuration
+const isDev = import.meta.env.MODE === 'development';
+
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [
+      {
+        name: '@lego/plugin-dashboard',
+        // Dev: Separate server │ Prod: Bundled via dynamic import
+        entry: isDev
+          ? 'http://localhost:3001'
+          : () => import('@lego/plugin-dashboard'),
+        activeWhen: '/dashboard',
+      },
+      {
+        name: '@lego/plugin-todo',
+        entry: isDev
+          ? 'http://localhost:3002'
+          : () => import('@lego/plugin-todo'),
+        activeWhen: '/todos',
+      },
+    ],
+  },
+});
+```
+
+### Step 2: Create plugin route wrapper
+
+**File:** `host/src/routes/_.tsx`
+
+```typescript
+import { Outlet } from '@modern-js/runtime/router';
+import { Shell } from '../layout';
+
+export default function PluginWrapper() {
+  return (
+    <Shell>
+      <Outlet />
+    </Shell>
+  );
+}
+```
+
+### Step 3: Create home/index route
+
+**File:** `host/src/routes/index.tsx`
+
+```typescript
+import { Link } from '@modern-js/runtime/router';
+import { ArrowRight, LayoutDashboard, CheckSquare, Shield } from 'lucide-react';
+import { useGlobalKernelState } from '../kernel/shared-state';
+
+export default function HomePage() {
+  const { isAuthenticated, user } = useGlobalKernelState();
+
+  return (
+    <div className="mx-auto max-w-4xl">
+      <div className="space-y-6">
+        {/* Hero */}
+        <div className="rounded-xl border bg-card p-8 text-center">
+          <h1 className="text-4xl font-bold tracking-tight">
+            Welcome to Lego-One
+          </h1>
+          <p className="mt-4 text-lg text-muted-foreground">
+            A modular SaaS boilerplate with microkernel architecture
+          </p>
+
+          {isAuthenticated ? (
+            <div className="mt-8">
+              <p className="text-muted-foreground">
+                Welcome back, {user?.name || 'User'}!
+              </p>
+            </div>
+          ) : (
+            <div className="mt-8 flex justify-center gap-4">
+              <Link
+                to="/login"
+                className="inline-flex items-center gap-2 rounded-lg bg-primary px-6 py-3 font-medium text-primary-foreground hover:bg-primary/90"
+              >
+                Sign In
+                <ArrowRight className="h-4 w-4" />
+              </Link>
+            </div>
+          )}
+        </div>
+
+        {/* Features */}
+        <div className="grid gap-6 md:grid-cols-3">
+          <div className="rounded-xl border bg-card p-6">
+            <div className="flex h-12 w-12 items-center justify-center rounded-lg bg-primary/10 text-primary">
+              <LayoutDashboard className="h-6 w-6" />
+            </div>
+            <h3 className="mt-4 text-lg font-semibold">Dashboard Plugin</h3>
+            <p className="mt-2 text-sm text-muted-foreground">
+              Overview of your account with stats and quick actions
+            </p>
+            <Link
+              to="/dashboard"
+              className="mt-4 inline-flex items-center text-sm font-medium text-primary hover:underline"
+            >
+              View Dashboard
+              <ArrowRight className="ml-1 h-4 w-4" />
+            </Link>
+          </div>
+
+          <div className="rounded-xl border bg-card p-6">
+            <div className="flex h-12 w-12 items-center justify-center rounded-lg bg-primary/10 text-primary">
+              <CheckSquare className="h-6 w-6" />
+            </div>
+            <h3 className="mt-4 text-lg font-semibold">Todo Plugin</h3>
+            <p className="mt-2 text-sm text-muted-foreground">
+              Manage your tasks with this example plugin
+            </p>
+            <Link
+              to="/todos"
+              className="mt-4 inline-flex items-center text-sm font-medium text-primary hover:underline"
+            >
+              View Todos
+              <ArrowRight className="ml-1 h-4 w-4" />
+            </Link>
+          </div>
+
+          <div className="rounded-xl border bg-card p-6">
+            <div className="flex h-12 w-12 items-center justify-center rounded-lg bg-primary/10 text-primary">
+              <Shield className="h-6 w-6" />
+            </div>
+            <h3 className="mt-4 text-lg font-semibold">Multi-Tenancy</h3>
+            <p className="mt-2 text-sm text-muted-foreground">
+              Built-in support for organizations and RBAC
+            </p>
+            <Link
+              to="/settings"
+              className="mt-4 inline-flex items-center text-sm font-medium text-primary hover:underline"
+            >
+              Manage Settings
+              <ArrowRight className="ml-1 h-4 w-4" />
+            </Link>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Step 4: Create dashboard plugin route
+
+**File:** `host/src/routes/dashboard._.tsx`
+
+```typescript
+import { useModuleApps } from '@modern-js/runtime/garfish';
+import { useGlobalKernelState } from '../kernel/shared-state';
+import { Skeleton } from '../kernel/components/ui/skeleton';
+
+export default function DashboardPluginRoute() {
+  const { isAuthenticated, isLoading } = useGlobalKernelState();
+  const moduleApps = useModuleApps();
+
+  const DashboardApp = moduleApps.find((app) => app.name === '@lego/plugin-dashboard');
+
+  if (isLoading) {
+    return (
+      <div className="space-y-6">
+        <Skeleton className="h-8 w-64" />
+        <div className="grid gap-6 md:grid-cols-3">
+          <Skeleton className="h-32" />
+          <Skeleton className="h-32" />
+          <Skeleton className="h-32" />
+        </div>
+        <Skeleton className="h-64" />
+      </div>
+    );
+  }
+
+  if (!isAuthenticated) {
+    return (
+      <div className="text-center">
+        <h1 className="text-2xl font-bold">Authentication Required</h1>
+        <p className="mt-2 text-muted-foreground">
+          Please sign in to access the dashboard.
+        </p>
+      </div>
+    );
+  }
+
+  if (!DashboardApp) {
+    return (
+      <div className="text-center">
+        <h1 className="text-2xl font-bold">Plugin Not Found</h1>
+        <p className="mt-2 text-muted-foreground">
+          The Dashboard plugin could not be loaded.
+        </p>
+      </div>
+    );
+  }
+
+  // The plugin app will be rendered here by Garfish
+  return DashboardApp.App;
+}
+```
+
+---
+
+## Task 8: Create Bootstrap and Root Entry
+
+**Files:**
+- Create: `host/src/bootstrap.tsx`
+- Create: `host/src/kernel/index.ts`
+- Modify: `host/src/App.tsx`
+
+### Step 1: Create bootstrap file
+
+**File:** `host/src/bootstrap.tsx`
+
+```typescript
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from '@modern-js/runtime/router';
+import App from './App';
+import { registerSharedState } from './kernel/shared-state';
+import { PocketBaseProvider } from './kernel/providers';
+import { QueryProvider } from './kernel/providers';
+import { ThemeProvider } from './kernel/providers';
+
+// Register shared state bridge for plugins
+registerSharedState();
+
+// Create root
+const container = document.getElementById('root');
+if (container) {
+  const root = createRoot(container);
+
+  root.render(
+    <StrictMode>
+      <BrowserRouter>
+        <ThemeProvider>
+          <QueryProvider>
+            <PocketBaseProvider>
+              <App />
+            </PocketBaseProvider>
+          </QueryProvider>
+        </ThemeProvider>
+      </BrowserRouter>
+    </StrictMode>
+  );
+}
+```
+
+### Step 2: Create kernel barrel export
+
+**File:** `host/src/kernel/index.ts`
+
+```typescript
+export * from './shared-state';
+export * from './providers';
+export * from './lib/utils';
+export * from './components';
+```
+
+### Step 3: Update App.tsx to use shell layout
+
+**File:** `host/src/App.tsx`
+
+```typescript
+import { Outlet } from '@modern-js/runtime/router';
+import './global.css';
+
+export default function App() {
+  return <Outlet />;
+}
+```
+
+### Step 4: Create basic UI components needed
+
+**File:** `host/src/kernel/components/ui/skeleton.tsx`
+
+```typescript
+import { cn } from '../../../lib/utils';
+
+function Skeleton({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn('animate-pulse rounded-md bg-muted', className)}
+      {...props}
+    />
+  );
+}
+
+export { Skeleton };
+```
+
+---
+
+## Task 9: Update Root Entry Point
+
+**Files:**
+- Create: `host/src/index.ts`
+
+### Step 1: Create entry point
+
+**File:** `host/src/index.ts`
+
+```typescript
+import '@modern-js/runtime/garfish';
+import './bootstrap';
+```
+
+---
+
+## Verification
+
+### Step 1: Build the host
+
+**Run:**
+
+```bash
+cd host
+pnpm run build
+```
+
+Expected: Build completes without errors.
+
+### Step 2: Start development server
+
+**Run:**
+
+```bash
+cd host
+pnpm run dev
+```
+
+Expected: Server starts on http://localhost:8080
+
+### Step 3: Verify functionality
+
+1. Open http://localhost:8080
+2. Should see the home page with "Welcome to Lego-One"
+3. Sidebar should be visible with navigation items
+4. Click menu items to verify routing works
+5. Open browser console and verify `window.__LEGO_KERNEL_STATE__` exists
+
+---
+
+## Summary
+
+After completing this document, you will have:
+
+1. ✅ Modern.js host app initialized with Garfish plugin
+2. ✅ Tailwind CSS configured with Shadcn-compatible theme
+3. ✅ Shared state bridge via `window.__LEGO_KERNEL_STATE__`
+4. ✅ Zustand store for auth, UI, and toast state
+5. ✅ Base providers (PocketBase, TanStack Query, Theme)
+6. ✅ Layout structure (Sidebar, Topbar, Shell)
+7. ✅ File-based routing with plugin wrappers
+8. ✅ Development vs Production plugin loading configuration
+
+**Next:** `04-auth-system.md` - Implement authentication, login/logout, and session management.
+
+---
+
+## Files Created
+
+```
+host/
+├── package.json
+├── tsconfig.json
+├── modern.config.ts
+├── tailwind.config.ts
+├── postcss.config.js
+├── .gitignore
+└── src/
+    ├── global.css
+    ├── index.ts
+    ├── bootstrap.tsx
+    ├── App.tsx
+    ├── modern.runtime.ts
+    ├── kernel/
+    │   ├── index.ts
+    │   ├── shared-state/
+    │   │   ├── types.ts
+    │   │   ├── store.ts
+    │   │   ├── bridge.ts
+    │   │   └── index.ts
+    │   ├── providers/
+    │   │   ├── PocketBaseProvider.tsx
+    │   │   ├── QueryProvider.tsx
+    │   │   ├── ThemeProvider.tsx
+    │   │   └── index.ts
+    │   ├── lib/
+    │   │   ├── utils.ts
+    │   │   └── cn.ts
+    │   └── components/
+    │       └── ui/
+    │           └── skeleton.tsx
+    ├── layout/
+    │   ├── Shell.tsx
+    │   ├── Sidebar.tsx
+    │   ├── Topbar.tsx
+    │   ├── MobileMenu.tsx
+    │   └── index.ts
+    └── routes/
+        ├── _.tsx
+        ├── index.tsx
+        └── dashboard._.tsx
+```