@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/guides/working-with-rooms.mdx

@@ -0,0 +1,566 @@
+---
+title: Working with Rooms
+description: Complete guide to implementing real-time presence tracking using the Blue Alba Platform's rooms system
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem, Code } from '@astrojs/starlight/components';
+import MermaidDiagram from '~/components/MermaidDiagram.astro';
+
+The Blue Alba Platform's rooms system provides real-time presence tracking for users within application contexts. This built-in feature enables you to see who is currently viewing or working in the same space, perfect for implementing collaborative features, live user indicators, and shared presence experiences.
+
+## Overview
+
+The rooms system enables you to:
+
+- Track which users are currently active in a specific context (room)
+- Display real-time user avatars showing who else is present
+- Build collaborative features without managing WebSocket infrastructure
+- Implement live indicators for shared documents, dashboards, or views
+- Show presence information with minimal code
+
+### Use Cases
+
+- **Collaborative Editing**: Show who else is viewing or editing a document
+- **Live Dashboards**: Display users currently viewing a dashboard
+- **Real-time Indicators**: Add "currently viewing" badges to any page
+- **Team Awareness**: Help teams know when colleagues are in the same context
+
+---
+
+## Architecture Overview
+
+The rooms system consists of two integrated components:
+
+<MermaidDiagram
+  title="Rooms System Architecture"
+  code={`graph TB
+    A[React Application<br/>with RoomsProvider]:::ui --> B[WebSocket Connection]:::ws
+    B --> C[pae-rooms-service<br/>WebSocket Gateway]:::service
+    C --> D[User Registry<br/>Rooms & Connections]:::data
+
+    E[Gateway<br/>Authentication]:::gateway --> C
+
+    F[Catalog Service]:::catalog --> A
+
+    A -->|joinRoom| C
+    A -->|leaveRoom| C
+    C -->|user_list broadcast| A
+
+    classDef ui fill:#87CEEB,color:#333
+    classDef ws fill:#FFB6C1,color:#333
+    classDef service fill:#90EE90,color:#333
+    classDef data fill:#FFD700,color:#333
+    classDef gateway fill:#DDA0DD,color:#333
+    classDef catalog fill:#F0E68C,color:#333`}
+/>
+
+### Backend Service: pae-rooms-service
+
+The backend is a NestJS WebSocket gateway that:
+- Manages real-time connections from UI applications
+- Tracks which users are in which rooms
+- Broadcasts user list updates to all connected clients
+- Runs behind the gateway (authentication handled upstream)
+
+<Aside type="note" title="Built-in Module">
+The rooms service is a **built-in platform module**, so no bootstrap configuration is needed. Simply deploy the service with the name 'pae-rooms-service'.
+</Aside>
+
+### Frontend Library
+
+The frontend components are available in the `@bluealba/pae-ui-react-core` package, providing:
+- `RoomsProvider`: React context provider managing WebSocket connection
+- `useRoom`: Hook for joining rooms and accessing user lists
+- `RoomAvatars`: Pre-built component for displaying user avatars
+
+---
+
+## Backend Deployment
+
+The `pae-rooms-service` must be deployed in your infrastructure.
+
+### Docker Compose Example
+
+```yaml
+services:
+  pae-rooms-service:
+    image: your-registry/pae-rooms-service:latest
+    environment:
+      - PORT=3000
+      - NODE_ENV=production
+    ports:
+      - "3010:3000"
+    networks:
+      - platform-network
+```
+
+<Aside type="tip" title="Zero Configuration">
+The rooms service requires no special configuration. Once deployed and accessible, it's ready to use. The gateway handles authentication and forwards user information via headers.
+</Aside>
+
+---
+
+## Frontend Integration
+
+This is where you'll spend most of your time - integrating rooms functionality into your React applications.
+
+### Installation
+
+The rooms functionality is available in the `@bluealba/pae-ui-react-core` package, which should already be installed in your UI module:
+
+```bash
+npm install @bluealba/pae-ui-react-core
+```
+
+### Setting Up the RoomsProvider
+
+The `RoomsProvider` must wrap any components that need to use rooms functionality. Typically, you'll add it at a high level in your component tree.
+
+```tsx
+import { RoomsProvider } from '@bluealba/pae-ui-react-core';
+
+function App() {
+  return (
+    <RoomsProvider>
+      {/* Your application components */}
+      <Dashboard />
+      <DocumentViewer />
+      <WorkspaceArea />
+    </RoomsProvider>
+  );
+}
+
+export default App;
+```
+
+**What the RoomsProvider does:**
+- Automatically establishes a WebSocket connection to the rooms service
+- Retrieves the service URL from the platform's application catalog
+- Manages connection state (loading, connected, closed, error)
+- Handles all WebSocket communication internally
+- Broadcasts user list updates to all consuming components
+- Cleans up the connection when unmounted
+
+<Aside type="caution">
+Any component attempting to use `useRoom` outside of a `RoomsProvider` will throw an error. Make sure the provider wraps all components that need rooms functionality.
+</Aside>
+
+### Using the useRoom Hook
+
+The `useRoom` hook is your primary interface for working with rooms. It automatically manages room membership and provides the current user list.
+
+#### Basic Usage (Automatic Mode)
+
+```tsx
+import { useRoom } from '@bluealba/pae-ui-react-core';
+
+function DocumentViewer({ documentId }) {
+  const { users, roomId, hasJoined } = useRoom(`document-${documentId}`);
+
+  return (
+    <div>
+      <h1>Document Viewer</h1>
+      <p>Room: {roomId}</p>
+      <p>Status: {hasJoined ? 'Joined' : 'Not in room'}</p>
+      <p>Currently viewing: {users.length} user(s)</p>
+
+      <ul>
+        {users.map(user => (
+          <li key={user.username}>{user.displayName}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+**Default Hook Behavior:**
+- Automatically joins the specified room when the component mounts
+- Automatically leaves the room when the component unmounts
+- Re-joins if the `roomId` parameter changes
+- Returns the current list of users in that room
+- Updates automatically when users join or leave
+
+#### Hook Options
+
+The `useRoom` hook accepts an optional second parameter for controlling automatic behavior:
+
+```typescript
+interface UseRoomOptions {
+  /**
+   * Automatically join the room when the hook is used.
+   * Defaults to true.
+   */
+  autoJoin?: boolean;
+  /**
+   * Automatically leave the room when the component unmounts.
+   * Defaults to true.
+   */
+  autoLeave?: boolean;
+}
+```
+
+**Default Options:** `{ autoJoin: true, autoLeave: true }` (backward compatible with previous versions)
+
+**Return Value:**
+```typescript
+interface UseRoomReturn {
+  users: RoomUser[];           // Array of users currently in the room
+  roomId: string;              // The current room ID
+  hasJoined: boolean;          // Whether the authenticated user has joined the room
+  joinRoom: () => void;        // Function to manually join the room
+  leaveRoom: () => void;       // Function to manually leave the room
+}
+```
+
+### Understanding RoomUser Type
+
+Each user in the room is represented by a `RoomUser` object:
+
+```typescript
+interface RoomUser {
+  username: string;      // Unique username from authentication
+  displayName: string;   // User's display name (human-readable)
+  rooms: string[];       // All rooms this user is currently in
+  color?: string;        // Auto-generated color for avatars
+}
+```
+
+**Key Points:**
+- `username`: Unique identifier, suitable for keys in React lists
+- `displayName`: What you should show to end users
+- `rooms`: Array of all room IDs the user has joined (useful for multi-room scenarios)
+- `color`: Automatically generated consistent color based on username, perfect for avatars
+
+---
+
+## Manual Room Control
+
+In some scenarios, you may want full control over when a user joins or leaves a room rather than relying on automatic behavior. The `useRoom` hook supports this through manual mode.
+
+<Aside type="tip" title="When to Use Manual Mode">
+Manual room control is useful when:
+- Room joining should be triggered by user action (e.g., clicking "Join Session")
+- You need conditional room participation based on user preferences or permissions
+- You want to implement "preview" mode where users can see the room before joining
+- You need to coordinate room joining with other asynchronous operations
+- You're building chat rooms, live sessions, or collaborative spaces with explicit join/leave actions
+</Aside>
+
+### Enabling Manual Mode
+
+Set both `autoJoin` and `autoLeave` to `false` to gain full control:
+
+```tsx
+import { useRoom } from '@bluealba/pae-ui-react-core';
+
+function ManualRoomExample({ roomId }) {
+  const { users, hasJoined, joinRoom, leaveRoom } = useRoom(roomId, {
+    autoJoin: false,
+    autoLeave: false,
+  });
+
+  return (
+    <div>
+      <div>
+        <p>Status: {hasJoined ? 'Joined' : 'Not Joined'}</p>
+        <p>Participants: {users.length}</p>
+      </div>
+
+      <div>
+        <button onClick={joinRoom} disabled={hasJoined}>
+          Join Room
+        </button>
+        <button onClick={leaveRoom} disabled={!hasJoined}>
+          Leave Room
+        </button>
+      </div>
+
+      {hasJoined && (
+        <ul>
+          {users.map(user => (
+            <li key={user.username}>{user.displayName}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+### Manual Control API
+
+**`joinRoom()`**: Manually join the room
+- Only works when `autoJoin: false`
+- Calling this when `autoJoin: true` will log a warning and be ignored
+- Safe to call multiple times (no-op if already joined)
+
+**`leaveRoom()`**: Manually leave the room
+- Only works when `autoLeave: false`
+- Calling this when `autoLeave: true` will log a warning and be ignored
+- Safe to call multiple times (no-op if not joined)
+
+**`hasJoined`**: Boolean indicating if the current user is in the room
+- Returns `true` if the authenticated user appears in the `users` array
+- Updates automatically when join/leave operations complete
+- Useful for conditional rendering and button states
+
+### Advanced Examples
+
+<Tabs>
+  <TabItem label="Conditional Joining">
+    ```tsx
+    function ConditionalRoom({ roomId, userHasPermission }) {
+      const { users, hasJoined, joinRoom, leaveRoom } = useRoom(roomId, {
+        autoJoin: false,
+        autoLeave: false,
+      });
+
+      useEffect(() => {
+        // Only join if user has permission
+        if (userHasPermission && !hasJoined) {
+          joinRoom();
+        }
+      }, [userHasPermission, hasJoined, joinRoom]);
+
+      useEffect(() => {
+        // Leave when component unmounts
+        return () => {
+          if (hasJoined) {
+            leaveRoom();
+          }
+        };
+      }, [hasJoined, leaveRoom]);
+
+      if (!userHasPermission) {
+        return <p>You don't have permission to join this room.</p>;
+      }
+
+      return (
+        <div>
+          <p>Participants: {users.length}</p>
+          {/* ... */}
+        </div>
+      );
+    }
+    ```
+    Join the room only when specific conditions are met
+  </TabItem>
+
+  <TabItem label="Preview Mode">
+    ```tsx
+    function RoomPreview({ roomId }) {
+      const [mode, setMode] = useState<'preview' | 'active'>('preview');
+      const { users, hasJoined, joinRoom, leaveRoom } = useRoom(roomId, {
+        autoJoin: false,
+        autoLeave: false,
+      });
+
+      useEffect(() => {
+        if (mode === 'active' && !hasJoined) {
+          joinRoom();
+        } else if (mode === 'preview' && hasJoined) {
+          leaveRoom();
+        }
+      }, [mode, hasJoined, joinRoom, leaveRoom]);
+
+      return (
+        <div>
+          <div>
+            <button onClick={() => setMode('preview')}>Preview</button>
+            <button onClick={() => setMode('active')}>Join Active</button>
+          </div>
+
+          <p>Mode: {mode}</p>
+          <p>Participants: {users.length}</p>
+
+          {mode === 'preview' && (
+            <p>You are viewing participant count without joining</p>
+          )}
+
+          {mode === 'active' && hasJoined && (
+            <ul>
+              {users.map(user => (
+                <li key={user.username}>{user.displayName}</li>
+              ))}
+            </ul>
+          )}
+        </div>
+      );
+    }
+    ```
+    Allow users to preview participant count before joining
+  </TabItem>
+
+  <TabItem label="Session Management">
+    ```tsx
+    function LiveSession({ sessionId }) {
+      const [sessionStarted, setSessionStarted] = useState(false);
+      const { users, hasJoined, joinRoom, leaveRoom } = useRoom(
+        `session-${sessionId}`,
+        { autoJoin: false, autoLeave: false }
+      );
+
+      const handleStartSession = async () => {
+        // Perform any async setup
+        await initializeSession(sessionId);
+
+        // Then join the room
+        joinRoom();
+        setSessionStarted(true);
+      };
+
+      const handleEndSession = async () => {
+        // Leave the room first
+        leaveRoom();
+
+        // Then cleanup
+        await cleanupSession(sessionId);
+        setSessionStarted(false);
+      };
+
+      useEffect(() => {
+        // Cleanup on unmount
+        return () => {
+          if (hasJoined) {
+            leaveRoom();
+          }
+        };
+      }, [hasJoined, leaveRoom]);
+
+      return (
+        <div>
+          {!sessionStarted ? (
+            <button onClick={handleStartSession}>
+              Start Live Session
+            </button>
+          ) : (
+            <>
+              <p>Session Active - {users.length} participants</p>
+              <button onClick={handleEndSession}>
+                End Session
+              </button>
+            </>
+          )}
+        </div>
+      );
+    }
+    ```
+    Coordinate room joining with other async operations
+  </TabItem>
+</Tabs>
+
+<Aside type="caution">
+**Important Behavior Notes:**
+- When `autoJoin: true` (default), calling `joinRoom()` manually will log a warning and be ignored
+- When `autoLeave: true` (default), calling `leaveRoom()` manually will log a warning and be ignored
+- Always check the console for warnings if manual join/leave isn't working as expected
+- The `hasJoined` flag is based on the authenticated user's presence in the `users` array
+</Aside>
+
+### Displaying User Avatars with RoomAvatars
+
+The `RoomAvatars` component provides a beautiful, ready-to-use interface for displaying room users:
+
+```tsx
+import { useRoom, RoomAvatars } from '@bluealba/pae-ui-react-core';
+
+function DashboardHeader({ dashboardId }) {
+  const { users } = useRoom(`dashboard-${dashboardId}`);
+
+  return (
+    <header>
+      <h1>Analytics Dashboard</h1>
+
+      <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+        <span>Currently viewing:</span>
+        <RoomAvatars
+          users={users}
+          size="md"
+          maxVisible={5}
+          overlap={true}
+        />
+      </div>
+    </header>
+  );
+}
+```
+
+**Component Features:**
+- Renders circular avatars with user initials
+- Automatically uses the user's generated color
+- Supports three sizes: `sm` (24px), `md` (32px), `lg` (40px)
+- Can overlap avatars for a compact display
+- Shows overflow count when too many users (e.g., "+3")
+- Includes tooltips showing full display names
+- Optional click handlers for custom interactions
+
+**Props:**
+
+```typescript
+interface RoomAvatarsProps {
+  users: RoomUser[];                    // Array of users to display (required)
+  maxVisible?: number;                  // Max avatars before showing overflow (default: 5)
+  size?: 'sm' | 'md' | 'lg';           // Avatar size (default: 'md')
+  overlap?: boolean;                    // Whether avatars overlap (default: true)
+  className?: string;                   // Additional CSS classes
+  onUserClick?: (user: RoomUser) => void; // Optional click handler
+}
+```
+
+**Examples:**
+
+<Tabs>
+  <TabItem label="Compact Display">
+    ```tsx
+    <RoomAvatars
+      users={users}
+      size="sm"
+      maxVisible={3}
+      overlap={true}
+    />
+    ```
+    Perfect for tight spaces, shows 3 overlapping small avatars
+  </TabItem>
+
+  <TabItem label="Spacious List">
+    ```tsx
+    <RoomAvatars
+      users={users}
+      size="lg"
+      maxVisible={10}
+      overlap={false}
+    />
+    ```
+    Larger avatars with no overlap, suitable for prominent displays
+  </TabItem>
+
+  <TabItem label="Interactive">
+    ```tsx
+    <RoomAvatars
+      users={users}
+      size="md"
+      maxVisible={5}
+      onUserClick={(user) => {
+        console.log('Clicked user:', user.displayName);
+        // Open user profile, start chat, etc.
+      }}
+    />
+    ```
+    Adds click interaction to each avatar
+  </TabItem>
+</Tabs>
+
+---
+
+## Multi-Tenancy Awareness
+
+**Important**: Room IDs are **NOT** automatically scoped by tenant. If you need tenant isolation, you must include the tenant ID as part of the room name:
+
+```tsx
+// ✅ Good: Explicitly scoped by tenant
+const { users } = useRoom(`tenant-${tenantId}-dashboard-main`);
+
+// ⚠️ Caution: This is a global room across all tenants
+const { users } = useRoom('dashboard-main');
+```

package/docs/index.mdx

@@ -0,0 +1,57 @@
+---
+title: Blue Alba Platform
+description: a generic and extensible framework and tools for developing customer facing applications from scratch
+template: splash
+hero:
+  image:
+    alt: Blue Alba Platform Logo
+    dark: ~/assets/logo-dark.png
+    light: ~/assets/logo-light.png
+  tagline: A generic and extensible framework and tools for developing customer facing applications from scratch
+  actions:
+    - text: Get Started
+      link: /_/docs/getting-started/overview/
+      icon: right-arrow
+      variant: primary
+    - text: View Architecture
+      link: /_/docs/architecture/overview/
+      icon: open-book
+      variant: minimal
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## Key Features
+
+<CardGrid stagger>
+  <Card title="API Gateway" icon="star">
+    Powerful HTTP gateway with application routing, catalog management, HTTP/2 and WebSocket support, and Lambda integration for serverless functions.
+  </Card>
+
+  <Card title="Authentication & Security" icon="approve-check">
+    Multi-IDP authentication (Okta, EntraId, OneLogin, Github, Cognito), API keys support, user impersonation, and JWT-based security.
+  </Card>
+
+  <Card title="Authorization & Access Control" icon="approve-check-circle">
+    Comprehensive RBAC with permissions, operations, roles, groups management, and fine-grained access control throughout the platform.
+  </Card>
+
+  <Card title="Multi-Tenancy & Provisioning" icon="codeberg">
+    Built-in multi-tenant architecture with tenant context management and automated Okta tenant/roles/applications provisioning.
+  </Card>
+
+  <Card title="Micro-Frontend Architecture" icon="puzzle">
+    React-based micro-frontends using single-spa with platform Shell UI and Administration UI for independent development and deployment.
+  </Card>
+
+  <Card title="User & State Management" icon="seti:favicon">
+    Complete user management with groups, saved views, bookmarks, and user-related data persistence.
+  </Card>
+
+  <Card title="Developer Experience" icon="rocket">
+    Comprehensive development tools including templates, conventions, shared libraries, frameworks, and platform bootstrapping utilities.
+  </Card>
+</CardGrid>
+
+
+