@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/guides/creating-ui-modules.mdx

@@ -0,0 +1,1860 @@
+---
+title: Creating UI Modules
+description: Complete guide to creating React-based micro-frontend UI modules for the Blue Alba Platform
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+import MermaidDiagram from '~/components/MermaidDiagram.astro';
+
+The Blue Alba Platform uses a micro-frontend architecture built on React and single-spa, enabling you to develop, deploy, and integrate independent UI modules that compose into a cohesive application experience. This guide walks you through everything you need to create production-ready UI modules.
+
+## Overview
+
+UI modules are self-contained React applications that integrate seamlessly into the platform's shell. Each module runs independently but can communicate with other modules through the platform's shared state, extension points, and event system.
+
+---
+
+## Architecture
+
+The platform's micro-frontend architecture uses single-spa as the orchestration layer, with custom integrations for authorization, routing, and inter-module communication.
+
+<MermaidDiagram
+  title="Micro-Frontend Architecture"
+  code={`graph TB
+    A[Platform Shell<br/>pae-shell-ui]:::shell --> B[Application Catalog]:::catalog
+    B --> C[UI Module 1<br/>pae-admin-ui]:::module
+    B --> D[UI Module 2<br/>Custom App UI]:::module
+    B --> E[UI Module N<br/>...]:::module
+
+    F[pae-ui-react-core<br/>Shared Library]:::lib --> C
+    F --> D
+    F --> E
+
+    G[Gateway API]:::gateway --> H[Backend Services]:::services
+    C -.HTTP.-> G
+    D -.HTTP.-> G
+    E -.HTTP.-> G
+
+    I[single-spa<br/>Orchestrator]:::orchestrator --> A
+    I --> C
+    I --> D
+    I --> E
+
+    classDef shell fill:#90EE90,color:#333
+    classDef catalog fill:#FFD700,color:#333
+    classDef module fill:#87CEEB,color:#333
+    classDef lib fill:#FFB6C1,color:#333
+    classDef gateway fill:#DDA0DD,color:#333
+    classDef services fill:#F0E68C,color:#333
+    classDef orchestrator fill:#FFA07A,color:#333`}
+/>
+
+### Architecture Components
+
+- **Platform Shell**: The main container that hosts all UI modules and provides navigation
+- **Application Catalog**: Registry of all available modules and their routes
+- **UI Modules**: Independent React applications loaded dynamically
+- **pae-ui-react-core**: Shared library providing hooks, components, and utilities
+- **single-spa**: Runtime orchestration layer managing module lifecycles
+- **Gateway API**: Unified backend interface for all services
+
+---
+
+## Quick Start
+
+Create your first UI module in five steps:
+
+### 1. Create Project Structure
+
+```bash
+mkdir my-app-ui
+cd my-app-ui
+npm init -y
+```
+
+### 2. Install Dependencies
+
+```bash
+# Install SDK and core library as dev dependencies
+npm install --save-dev @bluealba/pae-ui-react-sdk
+npm install --save-dev @bluealba/pae-ui-react-core
+
+# Install runtime dependencies
+npm install react@18 react-dom@18
+npm install react-router@6 react-router-dom@6
+```
+
+### 3. Configure package.json
+
+```json
+{
+  "name": "@myorg/my-app-ui",
+  "version": "1.0.0",
+  "displayName": "My Application",
+  "scripts": {
+    "start": "pae-ui-sdk start",
+    "start:dev": "pae-ui-sdk start --dev",
+    "build": "pae-ui-sdk build",
+    "lint": "pae-ui-sdk lint",
+    "lint:fix": "pae-ui-sdk lint --fix"
+  },
+  "devDependencies": {
+    "@bluealba/pae-ui-react-sdk": "*",
+    "@bluealba/pae-ui-react-core": "*"
+  },
+  "dependencies": {
+    "@bluealba/pae-core": "*",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router": "^6.26.1",
+    "react-router-dom": "^6.26.1"
+  }
+}
+```
+
+### 4. Create Source Files
+
+Create the following file structure:
+
+```
+my-app-ui/
+├── package.json
+└── src/
+    ├── main.tsx          # Module entry point
+    ├── root.component.tsx  # Root React component
+    ├── menu.ts          # Navigation menu
+    └── Icon.tsx         # Application icon
+```
+
+### 5. Implement Core Files
+
+<Tabs>
+  <TabItem label="main.tsx">
+
+```typescript
+import React from "react";
+import ReactDOMClient from "react-dom/client";
+import { ErrorState, initializeMicroFrontend } from "@bluealba/pae-ui-react-core";
+import Root from "./root.component";
+
+export const { bootstrap, mount, unmount } = initializeMicroFrontend({
+  React,
+  ReactDOMClient,
+  rootComponent: Root,
+  errorBoundary(err) {
+    console.error(err);
+    return <ErrorState />
+  }
+});
+
+// Export menu for shell integration
+export { default as menu } from "./menu";
+
+// Export application icon
+export { default as icon } from './Icon';
+```
+
+</TabItem>
+
+  <TabItem label="root.component.tsx">
+
+```typescript
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+export default function Root() {
+  return (
+    <BrowserRouter basename="/my-app">
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+        <Route path="/about" element={<AboutPage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+
+function HomePage() {
+  return <h1>Welcome to My App</h1>;
+}
+
+function AboutPage() {
+  return <h1>About My App</h1>;
+}
+```
+
+</TabItem>
+
+  <TabItem label="menu.ts">
+
+```typescript
+export default [
+  {
+    label: 'Home',
+    path: '/',
+  },
+  {
+    label: 'Features',
+    items: [
+      {
+        label: 'Dashboard',
+        path: '/dashboard',
+        operations: ['my-app::dashboard::read']
+      },
+      {
+        label: 'Settings',
+        path: '/settings',
+        operations: ['my-app::settings::read']
+      }
+    ]
+  },
+  {
+    label: 'About',
+    path: '/about',
+  }
+];
+```
+
+</TabItem>
+
+  <TabItem label="Icon.tsx">
+
+```typescript
+const Icon = () => (
+  <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
+    <path d="M12 2L2 7v10c0 5.5 4.5 10 10 10s10-4.5 10-10V7L12 2z"
+          fill="currentColor"/>
+  </svg>
+);
+
+export default Icon;
+```
+
+</TabItem>
+</Tabs>
+
+Now run `npm run start:dev` to start the development server!
+
+---
+
+## Project Structure
+
+A typical UI module follows this structure:
+
+```
+my-app-ui/
+├── package.json           # Project configuration
+├── tsconfig.json         # TypeScript configuration (optional)
+├── webpack.config.js     # Custom webpack config (optional)
+├── assets/               # Static assets (images, fonts)
+│   └── logo.svg
+└── src/
+    ├── main.tsx          # Module entry point (required)
+    ├── root.component.tsx # Root component (required)
+    ├── menu.ts           # Navigation menu
+    ├── Icon.tsx          # Application icon
+    ├── views/            # Page components
+    │   ├── HomePage.tsx
+    │   ├── DashboardPage.tsx
+    │   └── SettingsPage.tsx
+    ├── components/       # Reusable components
+    │   ├── Header.tsx
+    │   └── Card.tsx
+    ├── hooks/            # Custom hooks
+    │   └── useMyData.ts
+    ├── services/         # API service layer
+    │   └── api.ts
+    ├── utils/            # Utility functions
+    │   └── helpers.ts
+    └── styles/           # Stylesheets
+        └── global.css
+```
+
+### Key Files Explained
+
+<CardGrid>
+  <Card title="main.tsx" icon="seti:javascript">
+    Entry point that initializes the micro-frontend using `initializeMicroFrontend()`. Exports lifecycle methods (bootstrap, mount, unmount) and optional menu/icon.
+  </Card>
+
+  <Card title="root.component.tsx" icon="react">
+    Root React component containing your application's main structure, typically including routing configuration.
+  </Card>
+
+  <Card title="menu.ts" icon="list">
+    Menu configuration exported for shell integration. Defines navigation structure with optional operation-based access control.
+  </Card>
+
+  <Card title="Icon.tsx" icon="seti:image">
+    SVG component displayed in the application selector. Should be 24x24px and use `currentColor` for theme support.
+  </Card>
+</CardGrid>
+
+---
+
+## Development Workflow
+
+### Running Locally with Docker
+
+The recommended way to develop UI modules is using Docker Compose, which provides a consistent development environment and automatic integration with the platform.
+
+### Project Structure Setup
+
+Your repositories should be organized at the same level:
+
+```
+my-projects/
+├── my-app-local/              # Local environment with docker-compose.yml
+│   └── docker-compose.yml
+└── my-app-ui/                 # Your UI module repository
+    ├── Dockerfile.development
+    ├── package.json
+    └── src/
+```
+
+<Aside type="note">
+The docker-compose.yml uses `${PWD}/../my-app-ui` to reference the UI repository. This requires both repositories to be siblings in the same parent directory.
+</Aside>
+
+### Step 1: Create Development Dockerfile
+
+Create a `Dockerfile.development` in your UI module repository:
+
+```dockerfile
+FROM node:20-alpine as development
+
+ENV NODE_ENV=development
+ENV PORT=80
+
+ARG BA_NPM_AUTH_TOKEN
+
+WORKDIR /app
+
+EXPOSE 80
+
+CMD ["npm", "run", "start:dev"]
+```
+
+**Key points:**
+- Uses Node 20 Alpine for a lightweight image
+- Sets `NODE_ENV=development` for development mode
+- Exposes port 80 (configurable)
+- Runs `start:dev` command for hot reload
+
+### Step 2: Configure Docker Compose
+
+Add your UI module to the `docker-compose.yml` in your local environment repository:
+
+```yaml
+services:
+  my-app-ui:
+    build:
+      context: ../my-app-ui
+      dockerfile: Dockerfile.development
+    ports:
+      - 9001:80
+    volumes:
+      - ${PWD}/../my-app-ui:/app
+    environment:
+      - NODE_ENV=development
+```
+
+**Configuration explained:**
+
+| Property | Description |
+|----------|-------------|
+| `context: ../my-app-ui` | Path to your UI repository (relative to compose file) |
+| `dockerfile: Dockerfile.development` | Development-specific Dockerfile |
+| `ports: 9001:80` | Maps host port 9001 to container port 80 |
+| `volumes` | Mounts your code for hot reload (changes reflect immediately) |
+| `environment` | Sets environment variables |
+
+### Step 3: Start Development Environment
+
+From your local environment repository:
+
+```bash
+# Start your UI module
+docker-compose up my-app-ui
+
+# Or start in detached mode
+docker-compose up -d my-app-ui
+
+# View logs
+docker-compose logs -f my-app-ui
+```
+
+**What happens:**
+1. Docker builds the development image
+2. Installs npm dependencies inside the container
+3. Starts the dev server with hot reload (`npm run start:dev`)
+4. Your code is mounted as a volume - changes trigger automatic rebuilds
+5. Module is accessible at `http://localhost:9001`
+
+---
+
+## Core Concepts
+
+### Initializing a Micro-Frontend
+
+The `initializeMicroFrontend()` function is the foundation of every UI module. It creates a single-spa application with platform integration.
+
+```typescript
+import { initializeMicroFrontend } from "@bluealba/pae-ui-react-core";
+
+export const { bootstrap, mount, unmount } = initializeMicroFrontend({
+  React,
+  ReactDOMClient,
+  rootComponent: Root,
+  errorBoundary(err, info) {
+    console.error(err);
+    // Return custom error UI
+    return <ErrorState error={err} />;
+  }
+});
+```
+
+**Configuration Options:**
+
+| Option | Type | Description | Required |
+|--------|------|-------------|----------|
+| `React` | React | React library instance | Yes |
+| `ReactDOMClient` | ReactDOMClient | React DOM client for rendering | Yes |
+| `rootComponent` | React.Component | Your application's root component | Yes |
+| `errorBoundary` | Function | Error boundary handler returning JSX | Yes |
+
+**Lifecycle Methods:**
+
+The function returns three methods that single-spa calls:
+
+- `bootstrap()`: Called once when module first loads (initialize resources)
+- `mount()`: Called when module becomes active (render to DOM)
+- `unmount()`: Called when module becomes inactive (cleanup)
+
+### Navigation and Routing
+
+Use React Router for internal navigation and the platform's `navigateTo()` for cross-module navigation.
+
+<Tabs>
+  <TabItem label="Internal Routing">
+
+```typescript
+import { BrowserRouter, Routes, Route, Link } from 'react-router-dom';
+
+export default function Root() {
+  return (
+    <BrowserRouter basename="/my-app">
+      <nav>
+        <Link to="/">Home</Link>
+        <Link to="/dashboard">Dashboard</Link>
+      </nav>
+
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+        <Route path="/dashboard" element={<DashboardPage />} />
+        <Route path="/settings" element={<SettingsPage />} />
+        <Route path="*" element={<NotFoundPage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+<Aside type="note">
+Always set `basename` to match your module's route in the catalog (e.g., `/my-app`).
+</Aside>
+
+</TabItem>
+
+  <TabItem label="Cross-Module Navigation">
+
+```typescript
+import { navigateTo } from '@bluealba/pae-ui-react-core';
+
+function NavigationExample() {
+  const goToAdmin = () => {
+    // Navigate to another module
+    navigateTo('/admin/users');
+  };
+
+  const goToExternal = () => {
+    // Open external link
+    window.open('https://example.com', '_blank');
+  };
+
+  return (
+    <div>
+      <button onClick={goToAdmin}>
+        Go to Admin
+      </button>
+      <button onClick={goToExternal}>
+        External Link
+      </button>
+    </div>
+  );
+}
+```
+
+</TabItem>
+
+  <TabItem label="Programmatic Navigation">
+
+```typescript
+import { useNavigate } from 'react-router-dom';
+import { navigateTo } from '@bluealba/pae-ui-react-core';
+
+function NavigationComponent() {
+  // Internal navigation (within module)
+  const navigate = useNavigate();
+
+  const handleInternalNav = () => {
+    navigate('/dashboard');
+  };
+
+  // External navigation (to other modules)
+  const handleExternalNav = () => {
+    navigateTo('/admin');
+  };
+
+  return (
+    <div>
+      <button onClick={handleInternalNav}>Dashboard</button>
+      <button onClick={handleExternalNav}>Admin Panel</button>
+    </div>
+  );
+}
+```
+
+</TabItem>
+
+  <TabItem label="Route Parameters">
+
+```typescript
+import { useParams, useSearchParams } from 'react-router-dom';
+
+function UserDetailPage() {
+  // Path parameters: /users/:userId
+  const { userId } = useParams();
+
+  // Query parameters: /users?tab=profile
+  const [searchParams] = useSearchParams();
+  const tab = searchParams.get('tab');
+
+  return (
+    <div>
+      <h1>User {userId}</h1>
+      <p>Current tab: {tab}</p>
+    </div>
+  );
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Authentication and Authorization
+
+The platform provides built-in authentication and operation-based authorization.
+
+<Tabs>
+  <TabItem label="useAuth Hook">
+
+```typescript
+import { useAuth } from '@bluealba/pae-ui-react-core';
+
+function ProfileComponent() {
+  const { authUser, hasAccess } = useAuth();
+
+  return (
+    <div>
+      <h2>Welcome, {authUser.displayName}</h2>
+      <p>Username: {authUser.username}</p>
+      <p>Email: {authUser.email}</p>
+      <p>Initials: {authUser.initials}</p>
+
+      {hasAccess('admin::users::write') && (
+        <button>Edit User</button>
+      )}
+    </div>
+  );
+}
+```
+
+**AuthUser Properties:**
+- `displayName`: Full name (e.g., "John Doe")
+- `username`: Username (e.g., "johndoe")
+- `email`: Email address
+- `givenName`: First name
+- `familyName`: Last name
+- `initials`: Initials (e.g., "JD")
+- `operations`: Array of granted operation strings
+
+</TabItem>
+
+  <TabItem label="Authorized Component">
+
+```typescript
+import { Authorized } from '@bluealba/pae-ui-react-core';
+
+function DashboardPage() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      {/* Render only if user has operations */}
+      <Authorized operations={['dashboard::read']}>
+        <DashboardContent />
+      </Authorized>
+
+      {/* Show alternative content if unauthorized */}
+      <Authorized
+        operations={['admin::access']}
+        forbiddenContent={<div>Admin access required</div>}
+      >
+        <AdminSection />
+      </Authorized>
+
+      {/* Multiple operations (user needs ALL) */}
+      <Authorized operations={['users::read', 'users::write']}>
+        <UserManagement />
+      </Authorized>
+    </div>
+  );
+}
+```
+
+**forbiddenContent Options:**
+```typescript
+// Render function
+forbiddenContent={({ operations }) => (
+  <NoAccessMessage operations={operations} />
+)}
+
+// Component reference
+forbiddenContent={NoAccessComponent}
+
+// Direct JSX
+forbiddenContent={<div>Access Denied</div>}
+```
+
+</TabItem>
+
+  <TabItem label="Route Protection">
+
+```typescript
+import { useAuth } from '@bluealba/pae-ui-react-core';
+import { Navigate } from 'react-router-dom';
+
+// Protected route wrapper
+function ProtectedRoute({
+  children,
+  operations
+}: {
+  children: React.ReactNode;
+  operations: string[];
+}) {
+  const { hasAccess } = useAuth();
+
+  if (!hasAccess(...operations)) {
+    return <Navigate to="/unauthorized" replace />;
+  }
+
+  return <>{children}</>;
+}
+
+// Usage in routes
+function Root() {
+  return (
+    <BrowserRouter basename="/my-app">
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+
+        <Route
+          path="/admin"
+          element={
+            <ProtectedRoute operations={['admin::access']}>
+              <AdminPage />
+            </ProtectedRoute>
+          }
+        />
+
+        <Route path="/unauthorized" element={<UnauthorizedPage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+</TabItem>
+
+  <TabItem label="Menu Authorization">
+
+```typescript
+// menu.ts
+export default [
+  {
+    label: 'Home',
+    path: '/',
+    // No operations = visible to all
+  },
+  {
+    label: 'Dashboard',
+    path: '/dashboard',
+    operations: ['my-app::dashboard::read']
+  },
+  {
+    label: 'Admin',
+    operations: ['my-app::admin::access'],
+    items: [
+      {
+        label: 'Users',
+        path: '/admin/users',
+        operations: ['my-app::users::read']
+      },
+      {
+        label: 'Settings',
+        path: '/admin/settings',
+        operations: ['my-app::settings::write']
+      }
+    ]
+  }
+];
+```
+
+The shell automatically filters menu items based on user operations.
+
+</TabItem>
+</Tabs>
+
+### Service Communication
+
+Communicate with backend services using the `useServiceInvoker` hook.
+
+<Tabs>
+  <TabItem label="Basic Usage">
+
+```typescript
+import { useServiceInvoker } from '@bluealba/pae-ui-react-core';
+
+function UsersComponent() {
+  const invoke = useServiceInvoker('@myorg/users-service');
+  const [users, setUsers] = useState([]);
+
+  useEffect(() => {
+    // GET request
+    invoke('/users', { method: 'GET' })
+      .then(res => res.json())
+      .then(setUsers)
+      .catch(console.error);
+  }, [invoke]);
+
+  return (
+    <ul>
+      {users.map(user => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+</TabItem>
+
+  <TabItem label="POST/PUT/DELETE">
+
+```typescript
+import { useServiceInvoker } from '@bluealba/pae-ui-react-core';
+
+function UserForm() {
+  const invoke = useServiceInvoker('@myorg/users-service');
+
+  const createUser = async (userData: any) => {
+    const response = await invoke('/users', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(userData)
+    });
+
+    if (!response.ok) {
+      throw new Error('Failed to create user');
+    }
+
+    return response.json();
+  };
+
+  const updateUser = async (userId: string, userData: any) => {
+    const response = await invoke(`/users/${userId}`, {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(userData)
+    });
+
+    return response.json();
+  };
+
+  const deleteUser = async (userId: string) => {
+    await invoke(`/users/${userId}`, {
+      method: 'DELETE'
+    });
+  };
+
+  // ... form implementation
+}
+```
+
+</TabItem>
+
+  <TabItem label="With React Query">
+
+```typescript
+import { useServiceInvoker } from '@bluealba/pae-ui-react-core';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+function UsersManagement() {
+  const invoke = useServiceInvoker('@myorg/users-service');
+  const queryClient = useQueryClient();
+
+  // Fetch users
+  const { data: users, isLoading } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => invoke('/users').then(res => res.json())
+  });
+
+  // Create user mutation
+  const createMutation = useMutation({
+    mutationFn: (userData: any) =>
+      invoke('/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(userData)
+      }).then(res => res.json()),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+    }
+  });
+
+  // Delete user mutation
+  const deleteMutation = useMutation({
+    mutationFn: (userId: string) =>
+      invoke(`/users/${userId}`, { method: 'DELETE' }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+    }
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {users?.map(user => (
+        <div key={user.id}>
+          {user.name}
+          <button onClick={() => deleteMutation.mutate(user.id)}>
+            Delete
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+</TabItem>
+
+  <TabItem label="Error Handling">
+
+```typescript
+import { useServiceInvoker } from '@bluealba/pae-ui-react-core';
+
+function RobustComponent() {
+  const invoke = useServiceInvoker('@myorg/my-service');
+
+  const fetchData = async () => {
+    try {
+      const response = await invoke('/data', { method: 'GET' });
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          throw new Error('Data not found');
+        } else if (response.status === 403) {
+          throw new Error('Access denied');
+        } else {
+          throw new Error(`Request failed: ${response.status}`);
+        }
+      }
+
+      const data = await response.json();
+      return data;
+
+    } catch (error) {
+      if (error instanceof TypeError) {
+        // Network error
+        console.error('Network error:', error);
+        throw new Error('Cannot connect to server');
+      }
+      throw error;
+    }
+  };
+
+  // ... component implementation
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Extension Points
+
+Extension points allow modules to declare customizable parts that other modules can extend.
+
+<Tabs>
+  <TabItem label="Declaring Extension Points">
+
+**Inline with Component:**
+
+```typescript
+import { ExtensionPoint } from '@bluealba/pae-ui-react-core';
+
+function DashboardPage() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      {/* Declare an extension point */}
+      <ExtensionPoint name="DashboardWidgets">
+        {/* Default content if not extended */}
+        <DefaultWidget />
+      </ExtensionPoint>
+
+      <ExtensionPoint name="DashboardActions" />
+    </div>
+  );
+}
+```
+
+**Whole Component as Extension Point:**
+
+```typescript
+import { extensionPoint } from '@bluealba/pae-ui-react-core';
+
+const CustomHeader: React.FC = () => {
+  return (
+    <header>
+      <h1>Default Header</h1>
+    </header>
+  );
+};
+
+// Set display name for extension point identification
+CustomHeader.displayName = 'ApplicationHeader';
+
+// Make entire component replaceable
+export default extensionPoint(CustomHeader);
+```
+
+</TabItem>
+
+  <TabItem label="Extending Extension Points">
+
+**Using Component:**
+
+```typescript
+import { ExtendExtensionPoint } from '@bluealba/pae-ui-react-core';
+
+function Root() {
+  return (
+    <div>
+      {/* Your app content */}
+      <MyAppContent />
+
+      {/* Extend another module's extension point */}
+      <ExtendExtensionPoint
+        module="@bluealba/pae-admin-ui"
+        point="DashboardWidgets"
+      >
+        <CustomWidget title="My Custom Widget">
+          <p>This content extends the admin dashboard!</p>
+        </CustomWidget>
+      </ExtendExtensionPoint>
+    </div>
+  );
+}
+```
+
+**Using Hook:**
+
+```typescript
+import { useExtendExtensionPoint } from '@bluealba/pae-ui-react-core';
+
+const CustomApplicationSelector = () => {
+  return <div>Custom App Selector</div>;
+};
+
+function Root() {
+  // Register extension programmatically
+  useExtendExtensionPoint(
+    '@bluealba/pae-shell-ui',
+    'ApplicationSelector',
+    CustomApplicationSelector
+  );
+
+  return <div>My App Content</div>;
+}
+```
+
+</TabItem>
+
+  <TabItem label="Real-World Example">
+
+```typescript
+// In pae-admin-ui: Declare extension point
+import { ExtensionPoint } from '@bluealba/pae-ui-react-core';
+
+function SettingsPage() {
+  return (
+    <div>
+      <h1>Settings</h1>
+
+      <section>
+        <h2>Core Settings</h2>
+        {/* Core settings content */}
+      </section>
+
+      {/* Allow other modules to add settings sections */}
+      <ExtensionPoint name="AdditionalSettings" />
+    </div>
+  );
+}
+
+// In custom-app-ui: Extend the settings page
+import { ExtendExtensionPoint } from '@bluealba/pae-ui-react-core';
+
+function Root() {
+  return (
+    <>
+      <MyAppRoutes />
+
+      <ExtendExtensionPoint
+        module="@bluealba/pae-admin-ui"
+        point="AdditionalSettings"
+      >
+        <section>
+          <h2>My App Settings</h2>
+          <CustomSettings />
+        </section>
+      </ExtendExtensionPoint>
+    </>
+  );
+}
+```
+
+</TabItem>
+</Tabs>
+
+---
+
+## Platform Integration
+
+### Registering in the Application Catalog
+
+UI modules must be registered in the catalog to be discovered and loaded by the shell.
+
+<Tabs>
+  <TabItem label="Via API">
+
+```bash
+POST /api/catalog
+Content-Type: application/json
+Authorization: Bearer <admin-jwt>
+
+{
+  "name": "@myorg/my-app-ui",
+  "type": "app",
+  "displayName": "My Application",
+  "baseUrl": "/my-app",
+  "host": "my-app-ui",
+  "port": 80,
+  "activationRoute": "/my-app",
+  "dependsOn": ["@bluealba/pae-shell-ui"]
+  "bundleFile": "my-app-ui.js",
+  "mountAtSelector": "#pae-shell-ui-content",
+  "customProps": {},
+  "applicationName": "my-app-id",
+  "authorization": {
+    "operations": []
+  }
+}
+```
+
+<Aside type="tip">
+  Use `"type": "tool"` instead of `"type": "app"` if your module should appear in the navbar tools section (bottom area) rather than the application selector. This is appropriate for platform utilities and administration modules such as Admin UI or Documentation UI.
+</Aside>
+
+</TabItem>
+
+  <TabItem label="Via Bootstrap">
+
+For automated deployments, include in bootstrap configuration:
+
+```json
+{
+  {
+    "name": "@myorg/my-app-ui",
+    "displayName": "My Application",
+    "type": "app",
+    "baseUrl": "/my-app",
+    "service": {
+      "host": "my-app-ui",
+      "port": 80
+    },
+    "ui": {
+      "route": "/my-app",
+      "mountAtSelector": "#pae-shell-ui-content",
+      "bundleFile": "my-app-ui.js",
+      "customProps": {}
+    },
+    "dependsOn": ["@bluealba/pae-shell-ui"]
+  },
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+### Menu Integration
+
+The shell automatically renders your menu in the navigation sidebar.
+
+<Tabs>
+  <TabItem label="Simple Menu">
+
+```typescript
+// menu.ts
+export default [
+  {
+    label: 'Home',
+    path: '/'
+  },
+  {
+    label: 'Dashboard',
+    path: '/dashboard'
+  },
+  {
+    label: 'Settings',
+    path: '/settings'
+  }
+];
+```
+
+</TabItem>
+
+  <TabItem label="Nested Menu">
+
+```typescript
+// menu.ts
+export default [
+  {
+    label: 'Home',
+    path: '/'
+  },
+  {
+    label: 'Management',
+    items: [
+      {
+        label: 'Users',
+        path: '/users'
+      },
+      {
+        label: 'Roles',
+        path: '/roles'
+      },
+      {
+        label: 'Permissions',
+        path: '/permissions'
+      }
+    ]
+  },
+  {
+    label: 'Reports',
+    items: [
+      {
+        label: 'Analytics',
+        path: '/reports/analytics'
+      },
+      {
+        label: 'Audit Log',
+        path: '/reports/audit'
+      }
+    ]
+  }
+];
+```
+
+</TabItem>
+
+  <TabItem label="With Operations">
+
+```typescript
+// menu.ts
+export default [
+  {
+    label: 'Home',
+    path: '/',
+    // No operations = visible to all
+  },
+  {
+    label: 'Dashboard',
+    path: '/dashboard',
+    operations: ['my-app::dashboard::read']
+  },
+  {
+    label: 'Admin',
+    // Parent requires operation
+    operations: ['my-app::admin::access'],
+    items: [
+      {
+        label: 'Users',
+        path: '/admin/users',
+        // Child inherits parent operations + own operations
+        operations: ['my-app::users::manage']
+      },
+      {
+        label: 'Settings',
+        path: '/admin/settings',
+        operations: ['my-app::settings::write']
+      }
+    ]
+  }
+];
+```
+
+Shell filters menu items based on user operations automatically.
+
+</TabItem>
+
+  <TabItem label="Dynamic Menu">
+
+```typescript
+// menu.ts - can export a function for dynamic menus
+export default function getMenu(context: any) {
+  const items = [
+    {
+      label: 'Home',
+      path: '/'
+    }
+  ];
+
+  // Add items conditionally
+  if (context.user.hasFeature('advanced')) {
+    items.push({
+      label: 'Advanced',
+      path: '/advanced'
+    });
+  }
+
+  return items;
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Application Icon
+
+Provide an icon for the application selector in the shell.
+
+```typescript
+// Icon.tsx
+const Icon = () => (
+  <svg
+    width="24"
+    height="24"
+    viewBox="0 0 24 24"
+    fill="none"
+  >
+    <path
+      d="M12 2L2 7v10c0 5.5 4.5 10 10 10s10-4.5 10-10V7L12 2z"
+      fill="currentColor"
+    />
+  </svg>
+);
+
+export default Icon;
+```
+
+**Icon Guidelines:**
+- Size: 24x24px viewBox
+- Color: Use `currentColor` for theme support
+- Format: Inline SVG component
+- Style: Simple, recognizable at small sizes
+- Export: Default export from `Icon.tsx`
+
+---
+
+## State Management
+
+Choose a state management solution based on your needs.
+
+<Tabs>
+  <TabItem label="React Context">
+
+```typescript
+// AppContext.tsx
+import { createContext, useContext, useState } from 'react';
+
+interface AppState {
+  user: any;
+  settings: any;
+}
+
+const AppContext = createContext<{
+  state: AppState;
+  setState: (state: Partial<AppState>) => void;
+} | null>(null);
+
+export function AppProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState<AppState>({
+    user: null,
+    settings: {}
+  });
+
+  const updateState = (updates: Partial<AppState>) => {
+    setState(prev => ({ ...prev, ...updates }));
+  };
+
+  return (
+    <AppContext.Provider value={{ state, setState: updateState }}>
+      {children}
+    </AppContext.Provider>
+  );
+}
+
+export function useAppState() {
+  const context = useContext(AppContext);
+  if (!context) throw new Error('useAppState must be used within AppProvider');
+  return context;
+}
+```
+
+</TabItem>
+
+  <TabItem label="Zustand">
+
+```typescript
+// store.ts
+import { create } from 'zustand';
+
+interface AppStore {
+  user: any;
+  settings: any;
+  setUser: (user: any) => void;
+  setSettings: (settings: any) => void;
+}
+
+export const useStore = create<AppStore>((set) => ({
+  user: null,
+  settings: {},
+  setUser: (user) => set({ user }),
+  setSettings: (settings) => set({ settings }),
+}));
+
+// Usage
+function Component() {
+  const user = useStore(state => state.user);
+  const setUser = useStore(state => state.setUser);
+
+  return <div>{user?.name}</div>;
+}
+```
+
+</TabItem>
+
+  <TabItem label="React Query">
+
+```typescript
+// Ideal for server state management
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      refetchOnWindowFocus: false,
+      retry: 1
+    }
+  }
+});
+
+function Root() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <App />
+    </QueryClientProvider>
+  );
+}
+```
+
+</TabItem>
+
+  <TabItem label="Platform State">
+
+```typescript
+// Access platform-wide state
+import { usePAEState } from '@bluealba/pae-ui-react-core';
+
+function Component() {
+  const paeState = usePAEState();
+
+  // Access catalog
+  console.log(paeState.catalog);
+
+  // Access current user
+  console.log(paeState.user);
+
+  // Access current application
+  console.log(paeState.currentApplication);
+
+  return <div>Component</div>;
+}
+```
+
+</TabItem>
+</Tabs>
+
+---
+
+## Best Practices
+
+### Component Organization
+
+<CardGrid>
+  <Card title="Feature-Based Structure" icon="folder">
+    Organize by feature/domain rather than technical type (components, hooks, etc.).
+  </Card>
+
+  <Card title="Colocation" icon="document">
+    Keep related files together: component, styles, tests, and types in the same directory.
+  </Card>
+
+  <Card title="Barrel Exports" icon="seti:javascript">
+    Use index files to create clean import paths and encapsulate internal structure.
+  </Card>
+
+  <Card title="Separation of Concerns" icon="setting">
+    Separate presentational components from container components and business logic.
+  </Card>
+</CardGrid>
+
+**Recommended Structure:**
+
+```
+src/
+├── features/
+│   ├── users/
+│   │   ├── components/
+│   │   │   ├── UserList.tsx
+│   │   │   ├── UserList.test.tsx
+│   │   │   ├── UserList.module.css
+│   │   │   └── index.ts
+│   │   ├── hooks/
+│   │   │   └── useUsers.ts
+│   │   ├── services/
+│   │   │   └── usersApi.ts
+│   │   ├── types/
+│   │   │   └── User.ts
+│   │   └── index.ts
+│   └── dashboard/
+├── shared/
+│   ├── components/
+│   ├── hooks/
+│   └── utils/
+├── main.tsx
+└── root.component.tsx
+```
+
+### Error Handling
+
+```typescript
+// Global error boundary
+import { ErrorBoundary } from 'react-error-boundary';
+
+function ErrorFallback({ error, resetErrorBoundary }: any) {
+  return (
+    <div role="alert">
+      <h2>Something went wrong</h2>
+      <pre>{error.message}</pre>
+      <button onClick={resetErrorBoundary}>Try again</button>
+    </div>
+  );
+}
+
+function Root() {
+  return (
+    <ErrorBoundary FallbackComponent={ErrorFallback}>
+      <App />
+    </ErrorBoundary>
+  );
+}
+
+// Error handling in async operations
+async function fetchData() {
+  try {
+    const response = await invoke('/data');
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    return await response.json();
+  } catch (error) {
+    console.error('Failed to fetch data:', error);
+    // Show user-friendly error message
+    showNotification('Failed to load data. Please try again.', 'error');
+    throw error;
+  }
+}
+```
+
+### Accessibility
+
+```typescript
+// Semantic HTML
+function AccessibleForm() {
+  return (
+    <form onSubmit={handleSubmit}>
+      <label htmlFor="username">
+        Username
+        <input
+          id="username"
+          type="text"
+          aria-required="true"
+          aria-describedby="username-help"
+        />
+      </label>
+      <span id="username-help">Enter your username</span>
+
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+
+// Keyboard navigation
+function AccessibleButton() {
+  return (
+    <button
+      onClick={handleClick}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          handleClick();
+        }
+      }}
+      aria-label="Close dialog"
+    >
+      ×
+    </button>
+  );
+}
+
+// Focus management
+function Modal({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
+  const modalRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      modalRef.current?.focus();
+    }
+  }, [isOpen]);
+
+  return (
+    <div
+      ref={modalRef}
+      role="dialog"
+      aria-modal="true"
+      tabIndex={-1}
+    >
+      {/* Modal content */}
+    </div>
+  );
+}
+```
+
+### Testing
+
+```typescript
+// Component testing
+import { render, screen, fireEvent } from '@testing-library/react';
+import { UserList } from './UserList';
+
+describe('UserList', () => {
+  it('renders users', () => {
+    const users = [{ id: '1', name: 'John' }];
+    render(<UserList users={users} />);
+
+    expect(screen.getByText('John')).toBeInTheDocument();
+  });
+
+  it('handles user click', () => {
+    const onUserClick = jest.fn();
+    const users = [{ id: '1', name: 'John' }];
+
+    render(<UserList users={users} onUserClick={onUserClick} />);
+
+    fireEvent.click(screen.getByText('John'));
+    expect(onUserClick).toHaveBeenCalledWith(users[0]);
+  });
+});
+
+// Hook testing
+import { renderHook } from '@testing-library/react';
+import { useAuth } from '@bluealba/pae-ui-react-core';
+
+describe('useAuth', () => {
+  it('returns auth user', () => {
+    const { result } = renderHook(() => useAuth());
+
+    expect(result.current.authUser).toBeDefined();
+  });
+});
+```
+
+---
+
+## Troubleshooting
+
+<Tabs>
+  <TabItem label="Build Failures">
+
+**Problem: Module not found errors**
+
+```
+ERROR in ./src/main.tsx
+Module not found: Error: Can't resolve '@bluealba/pae-ui-react-core'
+```
+
+**Solution:**
+```bash
+# Install missing dependencies
+npm install
+
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+---
+
+**Problem: TypeScript errors**
+
+```
+TS2307: Cannot find module '@bluealba/pae-ui-react-core'
+```
+
+**Solution:**
+```bash
+# Ensure types are available
+npm install --save-dev @types/react @types/react-dom
+
+# Rebuild
+npm run build
+```
+
+</TabItem>
+
+  <TabItem label="Runtime Errors">
+
+**Problem: Module doesn't load in shell**
+
+**Checklist:**
+1. Verify bundle URL is accessible:
+   ```bash
+   curl https://cdn.example.com/my-app/main.js
+   ```
+
+2. Check browser console for errors
+
+3. Verify catalog registration:
+   ```bash
+   curl -H "Authorization: Bearer $TOKEN" \
+     https://platform.example.com/api/catalog
+   ```
+
+4. Check module exports bootstrap, mount, unmount:
+   ```typescript
+   export const { bootstrap, mount, unmount } = initializeMicroFrontend(/*...*/);
+   ```
+
+---
+
+**Problem: Routing doesn't work**
+
+**Solution:**
+Ensure `basename` matches catalog route:
+
+```typescript
+// Catalog route: /my-app
+<BrowserRouter basename="/my-app">
+```
+
+</TabItem>
+
+  <TabItem label="Authorization Issues">
+
+**Problem: User can't access module**
+
+**Causes:**
+
+1. **Missing operation:**
+   - Check user operations in Admin UI
+   - Grant required operation to user/role
+
+2. **Wrong route:**
+   - Verify route in catalog matches navigation
+
+**Debug:**
+```typescript
+import { useAuth } from '@bluealba/pae-ui-react-core';
+
+function Debug() {
+  const { authUser } = useAuth();
+  console.log('User operations:', authUser.operations);
+  return null;
+}
+```
+
+</TabItem>
+
+  <TabItem label="Performance Issues">
+
+**Problem: Slow initial load**
+
+**Solutions:**
+
+1. **Code splitting:**
+   ```typescript
+   const HeavyComponent = lazy(() => import('./HeavyComponent'));
+   ```
+
+2. **Bundle analysis:**
+   ```bash
+   ANALYZE=true npm run build
+   ```
+
+3. **Optimize dependencies:**
+   ```json
+   // Use lighter alternatives
+   // dayjs instead of moment
+   // zustand instead of redux
+   ```
+
+---
+
+**Problem: Slow navigation**
+
+**Solution:**
+Preload routes:
+```typescript
+import { Link } from 'react-router-dom';
+
+<Link
+  to="/dashboard"
+  onMouseEnter={() => {
+    // Preload route component
+    import('./views/DashboardPage');
+  }}
+>
+  Dashboard
+</Link>
+```
+
+</TabItem>
+</Tabs>
+
+---
+
+## Deployment
+
+### Building for Production
+
+```bash
+# Build optimized bundle
+npm run build
+
+# Output: dist/main.js and dist/assets/
+```
+
+### Hosting Options
+
+<Tabs>
+
+  <TabItem label="Docker Container">
+
+```dockerfile
+FROM nginxinc/nginx-unprivileged:mainline-alpine-slim
+
+WORKDIR /usr/share/nginx/html
+
+COPY ./version.json ./version.json
+COPY ./dist /usr/share/nginx/html
+
+COPY ./nginx/default.conf /etc/nginx/conf.d/default.conf
+
+EXPOSE 8080
+```
+
+```nginx
+# nginx.conf
+server {
+  listen       8080;
+  listen  [::]:8080;
+  server_name  localhost;
+
+  location / {
+      root   /usr/share/nginx/html;
+      index  index.html index.htm;
+  }
+
+  location /version {
+      default_type application/json;
+      alias /usr/share/nginx/html/version.json;
+  }
+
+  error_page   500 502 503 504  /50x.html;
+  location = /50x.html {
+      root   /usr/share/nginx/html;
+  }
+}
+```
+
+Deploy:
+```bash
+docker build -t my-app-ui:1.0.0 .
+docker push registry.example.com/my-app-ui:1.0.0
+```
+
+</TabItem>
+</Tabs>
+
+### Versioning Strategy
+
+```bash
+# Semantic versioning
+v1.0.0 - Initial release
+v1.1.0 - New features (backward compatible)
+v1.1.1 - Bug fixes
+v2.0.0 - Breaking changes
+
+```
+
+---
+
+## Related Documentation
+
+- **[Architecture Overview](../architecture/overview)** - Understand platform architecture
+- **[Gateway Architecture](../architecture/gateway-architecture)** - Learn about the API gateway
+- **[Shell Architecture](../architecture/shell)** - Deep dive into the platform shell
+- **[UI Extension Points](../architecture/ui-extension-points)** - Master extension point patterns
+- **[Authorization System](../architecture/authorization-system)** - Understand operations and RBAC
+- **[Adding Documentation Sites](./adding-documentation-sites)** - Document your UI module
+- **[Using Feature Flags](./using-feature-flags)** - Implement feature toggles
+
+---