@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/adminide-modules/project-tools/tenant-management/tenants.md

@@ -0,0 +1,1117 @@
+# Tenant Management System - Comprehensive Documentation
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [What This Functionality Is About](#what-this-functionality-is-about)
+3. [How to Execute the Functionality](#how-to-execute-the-functionality)
+4. [Implementation Details](#implementation-details)
+5. [Component Architecture](#component-architecture)
+6. [State Management](#state-management)
+7. [GraphQL Integration](#graphql-integration)
+8. [Backend Architecture & Inngest Integration](#backend-architecture--inngest-integration)
+9. [Important Notes and Best Practices](#important-notes-and-best-practices)
+
+---
+
+## Overview
+
+The Tenant Management System is a comprehensive multi-tenant management solution built with React, TypeScript, XState, and GraphQL. It provides a complete CRUD interface for managing tenants within an organization, including tenant creation, editing, deletion, secret key management, and lifecycle operations.
+
+**Primary Entry Point:** `TenantDashboard.tsx`
+
+---
+
+## What This Functionality Is About
+
+### Core Purpose
+
+The Tenant Management System enables organizations to:
+
+1. **Manage Multiple Tenants**: Create, view, update, and delete tenant configurations within an organization
+2. **Environment-Based Organization**: Associate tenants with specific environments (development, staging, production) and projects
+3. **Secret Key Management**: Generate, view, and revoke API secret keys for tenant authentication
+4. **Lifecycle Management**: Handle tenant creation workflows, retry failed operations, and monitor tenant status
+5. **Multi-Project Support**: Link tenants to specific projects within an organization
+
+### Key Features
+
+- ✅ **Full CRUD Operations**: Create, Read, Update, Delete tenants
+- ✅ **Secret API Key Management**: Generate and manage client configurations with secret keys
+- ✅ **Status Tracking**: Monitor tenant status (active, pending, error, disabled, completed)
+- ✅ **Error Handling**: Retry failed tenant creation operations
+- ✅ **Project Integration**: Associate tenants with projects and environment tags
+- ✅ **Real-time Updates**: Automatic refetching and cache management
+- ✅ **Toast Notifications**: User-friendly success/error feedback
+- ✅ **State Machine Management**: Predictable state transitions using XState
+
+---
+
+## How to Execute the Functionality
+
+### Accessing the Tenant Dashboard
+
+1. **Navigate to the Route**: The Tenant Dashboard is accessible via a route that includes the organization name parameter (`orgName`)
+
+    ```typescript
+    // Route pattern: /organizations/:orgName/tenants
+    ```
+
+2. **Prerequisites**:
+    - User must be authenticated
+    - User must have appropriate permissions for the organization
+    - Organization must exist and be accessible
+
+### Creating a New Tenant
+
+1. **Click "Create Tenant" Button**: Located in the header of the tenant list or in the empty state
+2. **Fill Required Fields**:
+    - **Name**: Tenant name (minimum 3 characters)
+    - **Description**: Detailed description of the tenant
+    - **Project**: Select a project from the dropdown (optional)
+    - **Environment**: Select an environment tag (automatically populated based on selected project)
+    - **Secret API Keys**: Add at least one secret key with name and optional description
+3. **Submit**: Click "Create Tenant" button
+4. **Result**:
+    - Success: Tenant is created, modal closes, list refreshes, toast notification appears
+    - Error: Error message displayed in the form, toast notification shows error details
+
+### Viewing Tenant Details
+
+1. **Click Tenant Name**: Click on any tenant name in the list to view details
+2. **Actions Menu**: Click "Actions" dropdown and select "View Details"
+3. **Details Modal Shows**:
+    - Basic information (name, description, app name, environment, status, auth type)
+    - Creation and update timestamps
+    - Error messages (if any)
+    - Secret API Keys section with reveal/revoke functionality
+
+### Editing a Tenant
+
+1. **Open Actions Menu**: Click "Actions" button next to the tenant
+2. **Select "Edit"**: Opens the edit modal
+3. **Modify Fields**: Update name, description, environment, or project
+4. **Add New Secret Keys**: Add additional secret API keys (existing keys are preserved)
+5. **Submit**: Click "Update Tenant" button
+6. **Result**: Tenant is updated, modal closes, list refreshes, selected tenant is cleared
+
+### Deleting a Tenant
+
+1. **Open Actions Menu**: Click "Actions" button next to the tenant
+2. **Select "Delete"**: Confirmation dialog appears
+3. **Confirm**: Tenant is permanently deleted
+4. **Result**: Tenant removed from list, toast notification confirms deletion
+
+### Managing Secret API Keys
+
+#### Viewing Secret Keys
+
+- **In Tenant Details**: All secret keys are listed with their metadata
+- **Reveal Key**: Click "Reveal" button to view the actual secret value
+- **Copy Key**: After revealing, click "Copy" to copy to clipboard
+- **Hide Key**: Click "Hide" to conceal the secret value again
+
+#### Revoking Secret Keys
+
+1. **In Tenant Details**: Click "Revoke" button next to a secret key
+2. **Confirm**: Confirm the revocation in the modal
+3. **Result**: Key is permanently revoked and removed from the list
+
+#### Adding New Secret Keys
+
+- **During Creation**: Add keys in the create tenant form
+- **During Edit**: Add new keys in the edit form (existing keys remain unchanged)
+
+### Retrying Failed Tenant Creation
+
+1. **Identify Failed Tenant**: Look for tenants with status "error" (red badge)
+2. **Open Actions Menu**: Click "Actions" button
+3. **Select "Retry Creation"**: Only visible for tenants with error status
+4. **Result**: Retry process initiated, status updates accordingly
+
+### Regenerating Tenant Secret
+
+**Note**: This feature is currently commented out in the UI but available in the backend.
+
+---
+
+## Implementation Details
+
+### Component Hierarchy
+
+```
+TenantDashboard (Main Container)
+├── TenantList (Table View)
+│   └── Action Dropdown Menu
+├── TenantDetails (Modal - View Only)
+│   └── SecretKeyList (Secret Key Management)
+├── CreateTenantModal (Modal)
+│   └── TenantForm
+│       ├── SecretKeyModal (Add New Keys)
+│       └── SecretKeyList (Preview New Keys)
+├── EditTenantModal (Modal)
+│   └── TenantForm
+│       ├── SecretKeyList (Existing Keys)
+│       ├── SecretKeyList (New Keys to Add)
+│       └── SecretKeyModal (Add New Keys)
+└── Toast (Notifications)
+```
+
+### Key Components
+
+#### 1. TenantDashboard (`TenantDashboard.tsx`)
+
+**Purpose**: Main orchestrator component that manages the entire tenant management workflow.
+
+**Responsibilities**:
+
+- State machine initialization and management
+- GraphQL query/mutation orchestration
+- Event handling and state synchronization
+- Modal visibility management
+- Toast notification management
+
+**Key Features**:
+
+- Uses XState machine (`tenantMachine`) for predictable state management
+- Integrates with Apollo Client for GraphQL operations
+- Manages multiple modals (create, edit, details) with proper state isolation
+- Handles organization context via URL parameter (`orgName`)
+
+**State Management Flow**:
+
+```typescript
+// Initial load
+useEffect(() => {
+    send({ type: 'LOAD_TENANTS' });
+    await loadTenants({ variables: { orgName } });
+}, []);
+
+// State updates via machine events
+send({ type: 'SUCCESS', data: tenants });
+send({ type: 'ERROR', error: errorMessage });
+send({ type: 'SELECT_TENANT', tenant });
+```
+
+#### 2. TenantList (`TenantList.tsx`)
+
+**Purpose**: Displays tenants in a tabular format with action capabilities.
+
+**Features**:
+
+- Responsive table layout
+- Status badges with color coding
+- Environment tag badges
+- Action dropdown menu per tenant
+- Empty state with call-to-action
+- Loading state with spinner
+
+**Status Colors**:
+
+- `active`: Green
+- `pending`: Yellow
+- `error`: Red
+- `disabled`: Gray
+- `completed`: Blue
+
+**Environment Colors**:
+
+- `development`: Cyan
+- `staging`: Orange
+- `production`: Red
+
+**Action Menu Options**:
+
+- View Details
+- Edit
+- Retry Creation (only for error status)
+- Delete
+
+#### 3. TenantDetails (`TenantDetails.tsx`)
+
+**Purpose**: Modal component displaying comprehensive tenant information.
+
+**Displays**:
+
+- Basic information (name, description, app name)
+- Environment tag
+- Status badge
+- Auth type
+- Timestamps (created/updated)
+- Error messages (if applicable)
+- Secret API Keys section
+
+**Secret Key Integration**:
+
+- Embeds `SecretKeyList` component
+- Passes `send` function for state machine updates
+- Enables reveal/revoke actions
+
+#### 4. CreateTenantModal (`CreateTenantModal.tsx`)
+
+**Purpose**: Modal wrapper for tenant creation form.
+
+**Features**:
+
+- Full-screen overlay modal
+- Click-outside-to-close functionality
+- Responsive design (max-width: 4xl)
+- Integrates with `TenantForm` component
+
+#### 5. EditTenantModal (`EditTenantModal.tsx`)
+
+**Purpose**: Modal wrapper for tenant editing form.
+
+**Features**:
+
+- Similar to CreateTenantModal
+- Pre-populates form with existing tenant data
+- Handles update-specific logic
+
+#### 6. TenantForm (`TenantForm/TenantForm.tsx`)
+
+**Purpose**: Reusable form component for both create and edit operations.
+
+**Form Fields**:
+
+1. **Name** (required, min 3 chars)
+2. **Description** (required)
+3. **Project** (optional dropdown)
+4. **Environment** (required, auto-populated from project)
+5. **Secret API Keys** (required for creation, optional for edit)
+
+**Key Behaviors**:
+
+- **Project Selection**: Automatically fetches environment tags when project is selected
+- **Environment Auto-selection**: Sets first environment tag as default
+- **Validation**: Real-time validation with error messages
+- **Secret Key Management**:
+    - Create mode: Requires at least one key
+    - Edit mode: Shows existing keys separately from new keys
+    - New keys can be added via modal
+    - Existing keys cannot be modified (only revoked via details view)
+
+**State Synchronization**:
+
+- Updates XState machine on field changes
+- Validates form before submission
+- Handles loading and error states
+
+#### 7. SecretKeyList (`SecretKeyList/SecretKeyList.tsx`)
+
+**Purpose**: Displays and manages secret API keys.
+
+**Features**:
+
+- Table view of secret keys
+- Reveal/Hide functionality for secret values
+- Copy to clipboard
+- Revoke functionality with confirmation
+- Security warning banner
+- Loading states for async operations
+
+**Key Operations**:
+
+- `revealKey(keyId)`: Fetches and displays secret value
+- `revokeKey(keyId)`: Permanently deletes secret key
+- Uses `useSecretKeys` hook for API operations
+
+**Security Considerations**:
+
+- Secrets are hidden by default
+- One-time reveal (must click reveal for each key)
+- Confirmation required for revocation
+- Security best practices displayed in warning banner
+
+#### 8. Toast (`Toast/Toast.tsx`)
+
+**Purpose**: User notification system.
+
+**Types**:
+
+- `success`: Green background
+- `error`: Red background
+- `info`: Blue background
+- `warning`: Yellow background
+
+**Features**:
+
+- Auto-dismiss after 5 seconds (configurable)
+- Manual close button
+- Icon indicators per type
+- Fixed position (top-right)
+
+---
+
+---
+
+## State Management
+
+### XState Machine (`tenantMachine.ts`)
+
+The tenant management system uses XState for predictable state management.
+
+#### Machine Context
+
+```typescript
+interface TenantMachineContext {
+    tenant: Partial<ITenant>;
+    tenants: ITenant[];
+    selectedTenant?: ITenant;
+    formData: TenantFormData;
+    loading: boolean;
+    error?: string;
+    success?: string;
+    validationErrors: Record<string, string>;
+}
+```
+
+#### Machine States
+
+1. **idle**: Initial state, ready for actions
+2. **loadingTenants**: Fetching tenant list
+3. **loadingTenant**: Fetching single tenant details
+4. **creatingTenant**: Creating new tenant
+5. **updatingTenant**: Updating existing tenant
+6. **deletingTenant**: Deleting tenant
+7. **regeneratingSecret**: Regenerating tenant secret
+8. **retryingCreation**: Retrying failed tenant creation
+
+#### Key Events
+
+- `LOAD_TENANTS`: Initialize tenant list loading
+- `SELECT_TENANT`: Select a tenant for viewing/editing
+- `CREATE_TENANT`: Initiate tenant creation
+- `UPDATE_TENANT`: Initiate tenant update
+- `DELETE_TENANT`: Initiate tenant deletion
+- `SUCCESS`: Handle successful operation
+- `ERROR`: Handle error condition
+- `RESET`: Clear selected tenant and errors
+- `UPDATE_FORM`: Update form field in context
+- `REVOKE_SECRET_KEY`: Revoke a secret key
+
+#### Actions
+
+- `setTenants`: Update tenants array
+- `setSelectedTenant`: Update selected tenant
+- `addTenant`: Add new tenant to list
+- `updateTenantInList`: Update tenant in list
+- `removeTenant`: Remove tenant from list
+- `updateForm`: Update form data
+- `validateForm`: Validate form fields
+- `resetForm`: Clear form data
+- `setError`: Set error message
+- `setSuccess`: Set success message
+
+---
+
+## GraphQL Integration
+
+### Queries
+
+#### GetTenants
+
+```graphql
+query GetTenants($orgName: String!) {
+    tenants(orgName: $orgName) {
+        id
+        tenantId
+        name
+        description
+        appName
+        status
+        environmentTag {
+            id
+            name
+        }
+        project {
+            id
+            name
+        }
+        clientConfigurations {
+            id
+            name
+            description
+            createdAt
+        }
+        errorMessage
+        createdAt
+        updatedAt
+    }
+}
+```
+
+#### GetTenant
+
+```graphql
+query GetTenant($id: ID!) {
+  tenant(id: $id) {
+    # Same fields as GetTenants
+  }
+}
+```
+
+#### GetProjectsNameAndId
+
+```graphql
+query GetProjectsNameAndId($orgName: String!) {
+    getProjects(orgName: $orgName) {
+        data {
+            id
+            name
+        }
+    }
+}
+```
+
+#### GetEnvironmentTags
+
+```graphql
+query GetEnvironmentTags($projectId: ID!) {
+    getEnvironmentTags(projectId: $projectId) {
+        id
+        name
+    }
+}
+```
+
+### Mutations
+
+#### CreateTenant
+
+```graphql
+mutation CreateTenant($input: TenantInput!) {
+    createTenant(input: $input) {
+        tenant {
+            id
+            tenantId
+            name
+            # ... other fields
+        }
+        message
+    }
+}
+```
+
+**Input Structure**:
+
+```typescript
+{
+    name: string;
+    description: string;
+    environmentTag: string; // Environment tag ID
+    authType: AuthType.ClientSecret;
+    clientConfigurations: Array<{
+        name: string;
+        description?: string;
+    }>;
+    vault: string; // Project ID
+    organization: string; // Organization name/slug
+}
+```
+
+#### UpdateTenant
+
+```graphql
+mutation UpdateTenant($id: ID!, $input: TenantUpdateInput!) {
+    updateTenant(id: $id, input: $input) {
+        id
+        tenantId
+        name
+        # ... updated fields
+    }
+}
+```
+
+**Update Input**: Only includes changed fields (partial update)
+
+#### DeleteTenant
+
+```graphql
+mutation DeleteTenant($id: ID!) {
+    deleteTenant(id: $id)
+}
+```
+
+#### RegenerateTenantSecret
+
+```graphql
+mutation RegenerateTenantSecret($id: ID!) {
+    regenerateTenantSecret(id: $id) {
+        id
+        # ... tenant fields
+    }
+}
+```
+
+#### RetryTenantCreation
+
+```graphql
+mutation RetryTenantCreation($tenantId: ID!) {
+    retryTenantCreation(tenantId: $tenantId)
+}
+```
+
+### Apollo Client Configuration
+
+- **Fetch Policy**: `cache-and-network` for queries (ensures fresh data)
+- **Fetch Policy**: `network-only` for tenant details (always fetch latest)
+- **Refetch Queries**: Automatic refetch after mutations
+- **Error Handling**: Centralized via `onError` callbacks
+- **Loading States**: Managed via Apollo hooks
+
+---
+
+## Backend Architecture & Inngest Integration
+
+### Overview
+
+The Tenant Management System uses an **event-driven architecture** with **Inngest** for asynchronous background processing. The backend service handles immediate database operations, while Inngest functions handle external integrations (primarily Keycloak client management) and long-running workflows.
+
+### Architecture Pattern
+
+The system follows a **separation of concerns** pattern:
+
+1. **Service Layer** (`TenantService`): Handles immediate database operations and triggers Inngest events
+2. **Inngest Functions**: Handle external integrations (Keycloak) and async workflows
+3. **No Infinite Loops**: Inngest functions perform different operations than the service methods that trigger them
+
+### Backend Service Layer
+
+#### TenantService (`tenant-service.ts`)
+
+**Purpose**: Core service for tenant CRUD operations and business logic.
+
+**Key Responsibilities**:
+
+- Database operations (create, read, update, delete)
+- Tenant ID resolution and mapping
+- Secret key generation and management
+- Inngest event triggering for async operations
+- Status management (pending → active → error)
+
+**Key Methods**:
+
+##### `createTenant(input: ITenantInput)`
+
+**Flow**:
+
+1. Generates unique `jobId` for tracking
+2. Creates tenant record in MongoDB with status `Pending`
+3. Generates `connectionId` (secret for tenant connection)
+4. Creates `appName` from tenant name (lowercase, hyphenated)
+5. Maps `vault` input to `project` (MongoDB ObjectId)
+6. Maps `organization` input to ObjectId
+7. **Triggers Inngest Event**: `TENANT_MGMT_CREATE_CLIENT_EVENT` for Keycloak client creation
+8. Returns tenant with `jobId` and success message
+
+**Inngest Event Payload**:
+
+```typescript
+{
+  name: WorkflowNamespace.TENANT_MGMT_CREATE_CLIENT_EVENT,
+  data: {
+    tenantId: tenant.id,
+    id: tenant._id, // MongoDB ObjectId
+    clientConfigurations: input.clientConfigurations
+  }
+}
+```
+
+##### `updateTenant(id: string, input: Partial<ITenantInput>)`
+
+**Flow**:
+
+1. Finds existing tenant by `tenantId`
+2. Updates basic fields (name, description, environmentTag, project)
+3. **Preserves existing client configurations**
+4. Merges new configurations with existing ones
+5. **Triggers Inngest Event**: `TENANT_MGMT_CREATE_CLIENT_EVENT` if new keys are added
+6. Returns updated tenant
+
+**Important**: Only new client configurations trigger Inngest events. Existing keys remain unchanged.
+
+##### `deleteTenant(id: string)`
+
+**Flow**:
+
+1. Finds tenant by `tenantId`
+2. Deletes tenant from MongoDB
+3. **Triggers Inngest Event**: `TENANT_MGMT_DELETE_TENANT_EVENT` with client configurations
+4. Returns success boolean
+
+**Inngest Event Payload**:
+
+```typescript
+{
+  name: WorkflowNamespace.TENANT_MGMT_DELETE_TENANT_EVENT,
+  data: {
+    clientConfiguraiton: tenant.clientConfigurations // Note: typo in original code
+  }
+}
+```
+
+##### `getSecretKeyValue(tenantId: string, keyId: string)`
+
+**Purpose**: Reveals secret key value on-demand (deterministic generation).
+
+**Flow**:
+
+1. Finds tenant by `tenantId`
+2. Locates client configuration by `keyId`
+3. **Generates secret deterministically** using `generateSecretFromName()`
+4. Creates base64-encoded secret: `clientId:secret`
+5. Returns secret value
+
+**Security**: Secrets are not stored; they are regenerated deterministically when needed.
+
+##### `revokeSecretKey(tenantId: string, keyId: string)`
+
+**Flow**:
+
+1. Finds tenant and secret key
+2. Removes key from `clientConfigurations` array
+3. Updates tenant in database
+4. **Triggers Inngest Event**: `TENANT_MGMT_DELETE_TENANT_EVENT` to delete Keycloak client
+5. Returns revoked key ID
+
+##### `retryTenantCreation(tenantId: string)`
+
+**Flow**:
+
+1. Validates tenant exists and has `error` status
+2. Increments retry count
+3. Resets status to `Pending`
+4. Generates new `jobId`
+5. Updates tenant in database
+6. Returns success boolean
+
+**Note**: This only resets the status. The actual retry is handled by background processes monitoring pending tenants.
+
+#### Tenant ID Resolution
+
+**Method**: `resolveTenantId(tenantId: string)`
+
+**Purpose**: Maps special tenant IDs to actual IDs.
+
+**Implementation**:
+
+```typescript
+private resolveTenantId(tenantId: string): string {
+  return defaultTenantIdMapper(tenantId);
+}
+```
+
+**Mapping Logic**:
+
+- `'default'` → `config.STATIC_TENANT_ID` (from environment)
+- All other IDs → Returned as-is
+
+**Usage**: All tenant lookups use this method to ensure consistent ID resolution.
+
+### Inngest Event-Driven Workflow
+
+#### Event Namespace
+
+All tenant management events use the `WorkflowNamespace` constants:
+
+**Trigger Events** (what functions listen for):
+
+- `TENANT_MGMT_CREATE_CLIENT_EVENT`: Create Keycloak clients
+- `TENANT_MGMT_DELETE_TENANT_EVENT`: Delete Keycloak clients
+
+**Function IDs**:
+
+- `TENANT_MGMT_CREATE_CLIENT`: Function that creates clients
+- `TENANT_MGMT_DELETE_TENANT`: Function that deletes clients
+
+#### Inngest Functions
+
+##### 1. `createTenantClientFunction`
+
+**Purpose**: Creates Keycloak clients for tenant secret keys.
+
+**Trigger**: `TENANT_MGMT_CREATE_CLIENT_EVENT`
+
+**Event Data**:
+
+```typescript
+{
+    tenantId: string;
+    id: string; // MongoDB ObjectId
+    clientConfigurations: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+```
+
+**Workflow Steps**:
+
+1. **Step: `create-secret-keys`**
+    - Iterates through `clientConfigurations`
+    - For each key without `clientId`:
+        - Generates deterministic secret using `generateSecretFromName(keyName, tenantId)`
+        - Creates unique `clientId`: `tenant-${tenantId}-key-${timestamp}`
+        - Calls `KeycloakInternalAdminService.Instance.createClientWithClientSecretAuthType(clientId, clientSecret)`
+        - Creates key object with metadata
+    - Returns array of created keys with `clientId` and metadata
+
+2. **Step: `update-tenant-with-keys`**
+    - Calls `tenantService.update()` with:
+        - Updated `clientConfigurations` array (with `clientId` values)
+        - Status set to `Active`
+    - Returns success confirmation
+
+**Result**: Tenant status changes from `Pending` → `Active`, and Keycloak clients are created.
+
+**Error Handling**: If Keycloak client creation fails, tenant status remains `Pending` or changes to `Error`.
+
+##### 2. `deleteTenantClientFunction`
+
+**Purpose**: Deletes Keycloak clients when tenant or secret keys are revoked.
+
+**Trigger**: `TENANT_MGMT_DELETE_TENANT_EVENT`
+
+**Event Data**:
+
+```typescript
+{
+  clientConfiguration: IClientConfigurations[] // Array of client configs to delete
+}
+```
+
+**Workflow Steps**:
+
+1. **Step: `delete-tenant`**
+    - Iterates through `clientConfiguration` array
+    - For each config with `clientId`:
+        - Calls `keycloakAdminService.deleteClient(clientId)`
+        - Continues even if individual deletions fail
+    - Returns success
+
+**Error Handling**: Individual client deletion failures are logged but don't stop the process.
+
+##### 3. `createTenantFunction` (Legacy/Alternative)
+
+**Purpose**: Alternative tenant creation workflow (used in some contexts).
+
+**Trigger**: `TENANT_MGMT_CREATE_TENANT_EVENT`
+
+**Note**: This function creates a tenant from project data, typically used in project creation workflows rather than direct tenant creation.
+
+### Secret Key Generation
+
+#### Deterministic Secret Generation
+
+**Function**: `generateSecretFromName(keyName: string, tenantId: string)`
+
+**Purpose**: Generate reproducible secrets for API keys.
+
+**Algorithm**:
+
+1. Uses salt from environment: `process.env.SECRET_KEY_SALT` or default
+2. Creates data string: `${keyName}:${tenantId}:${salt}`
+3. Generates SHA-256 hash
+4. Encodes as base64
+5. Removes non-alphanumeric characters
+6. Limits to 32 characters (Keycloak requirement)
+
+**Benefits**:
+
+- Secrets can be regenerated on-demand
+- No need to store secrets in database
+- Consistent across regenerations
+
+**Usage**:
+
+- When revealing secret keys (on-demand generation)
+- When creating new Keycloak clients
+
+#### Secret Format
+
+**For API Usage**: Secrets are base64-encoded as `clientId:secret`
+
+**Example**:
+
+```typescript
+const secret = generateSecretFromName('ACCESS_KEY', 'tenant-123');
+const clientSecret = Buffer.from(`${clientId}:${secret}`).toString('base64');
+// Returns: "Y2xpZW50SWQ6c2VjcmV0VmFsdWU="
+```
+
+### Complete Data Flow
+
+#### Creating a Tenant
+
+```
+1. Frontend: User submits create tenant form
+   ↓
+2. GraphQL Mutation: createTenant(input)
+   ↓
+3. TenantService.createTenant()
+   ├── Creates tenant in MongoDB (status: Pending)
+   ├── Generates jobId, connectionId, appName
+   └── Triggers Inngest Event: TENANT_MGMT_CREATE_CLIENT_EVENT
+   ↓
+4. Returns tenant to frontend (status: Pending)
+   ↓
+5. Inngest Function: createTenantClientFunction
+   ├── Step 1: Create Keycloak clients
+   │   ├── Generate secrets deterministically
+   │   ├── Create clientId for each key
+   │   └── Call Keycloak API to create clients
+   └── Step 2: Update tenant
+       ├── Add clientId to each configuration
+       └── Set status: Active
+   ↓
+6. Tenant status: Pending → Active
+```
+
+#### Updating a Tenant (Adding New Keys)
+
+```
+1. Frontend: User adds new secret keys in edit form
+   ↓
+2. GraphQL Mutation: updateTenant(id, input)
+   ↓
+3. TenantService.updateTenant()
+   ├── Preserves existing clientConfigurations
+   ├── Merges new configurations
+   └── Triggers Inngest Event: TENANT_MGMT_CREATE_CLIENT_EVENT
+   ↓
+4. Returns updated tenant to frontend
+   ↓
+5. Inngest Function: createTenantClientFunction
+   ├── Step 1: Create Keycloak clients for NEW keys only
+   └── Step 2: Update tenant with all keys (existing + new)
+```
+
+#### Revoking a Secret Key
+
+```
+1. Frontend: User clicks "Revoke" on a secret key
+   ↓
+2. GraphQL Mutation: revokeSecretKey(tenantId, keyId)
+   ↓
+3. TenantService.revokeSecretKey()
+   ├── Removes key from clientConfigurations array
+   ├── Updates tenant in database
+   └── Triggers Inngest Event: TENANT_MGMT_DELETE_TENANT_EVENT
+   ↓
+4. Returns success to frontend
+   ↓
+5. Inngest Function: deleteTenantClientFunction
+   └── Step: Delete Keycloak client by clientId
+```
+
+#### Deleting a Tenant
+
+```
+1. Frontend: User confirms tenant deletion
+   ↓
+2. GraphQL Mutation: deleteTenant(id)
+   ↓
+3. TenantService.deleteTenant()
+   ├── Deletes tenant from MongoDB
+   └── Triggers Inngest Event: TENANT_MGMT_DELETE_TENANT_EVENT
+   ↓
+4. Returns success to frontend
+   ↓
+5. Inngest Function: deleteTenantClientFunction
+   └── Step: Delete all Keycloak clients for tenant
+```
+
+### Keycloak Integration
+
+#### Client Creation
+
+**Service**: `KeycloakInternalAdminService.Instance.createClientWithClientSecretAuthType()`
+
+**Parameters**:
+
+- `clientId`: Unique identifier (format: `tenant-{tenantId}-key-{timestamp}`)
+- `clientSecret`: Deterministically generated secret (32 chars, alphanumeric)
+
+**Configuration**:
+
+- Authentication type: Client Secret
+- Client credentials flow enabled
+- Scopes and permissions configured per tenant requirements
+
+#### Client Deletion
+
+**Service**: `keycloakAdminService.deleteClient(clientId)`
+
+**Behavior**:
+
+- Permanently removes client from Keycloak
+- All associated tokens become invalid
+- Cannot be undone
+
+### Status Lifecycle
+
+```
+Pending → Active (when Keycloak clients created successfully)
+Pending → Error (when Keycloak client creation fails)
+Error → Pending (when retry is initiated)
+```
+
+**Status Transitions**:
+
+- **Pending**: Initial state, waiting for Keycloak client creation
+- **Active**: All Keycloak clients created successfully
+- **Error**: Keycloak client creation failed (error message stored)
+- **Disabled**: Manually disabled (not used in current flow)
+- **Completed**: Legacy status (not commonly used)
+
+### Error Handling
+
+#### Service Layer Errors
+
+- **Database Errors**: Thrown immediately, caught by GraphQL resolver
+- **Validation Errors**: Thrown before database operations
+- **Inngest Trigger Errors**: Logged but don't fail the operation (event is queued)
+
+#### Inngest Function Errors
+
+- **Keycloak API Errors**: Logged, tenant status may remain `Pending` or change to `Error`
+- **Partial Failures**: Individual client creation failures don't stop the entire process
+- **Retry Mechanism**: Failed operations can be retried via `retryTenantCreation()`
+
+### Performance Considerations
+
+#### Async Processing
+
+- **Immediate Response**: Service methods return immediately after triggering Inngest events
+- **Background Processing**: Keycloak operations happen asynchronously
+- **Status Updates**: Frontend can poll or use subscriptions to track status changes
+
+#### Database Operations
+
+- **Optimistic Updates**: Frontend updates immediately, backend confirms asynchronously
+- **Idempotency**: Inngest functions are designed to be safely retried
+- **Transaction Safety**: Database updates are atomic, but Keycloak operations are separate
+
+### Monitoring & Debugging
+
+#### Logging
+
+- **Service Layer**: Uses structured logging with tenant context
+- **Inngest Functions**: Console logs for debugging (can be enhanced with proper logging)
+- **Keycloak Operations**: Errors logged with clientId and tenantId
+
+#### Tracking
+
+- **Job IDs**: Each tenant creation gets a unique `jobId` for tracking
+- **Retry Count**: Failed operations track retry attempts
+- **Error Messages**: Stored in `tenant.errorMessage` for debugging
+
+### Best Practices
+
+1. **Always Check Status**: Before operations, verify tenant status
+2. **Handle Async Nature**: Keycloak operations are async; don't expect immediate completion
+3. **Idempotent Operations**: Inngest functions can be safely retried
+4. **Error Recovery**: Use `retryTenantCreation()` for failed operations
+5. **Secret Security**: Never log or expose secret values
+6. **Client ID Uniqueness**: Ensure clientIds are unique across all tenants
+
+---
+
+## Important Notes and Best Practices
+
+### 1. Tenant ID vs ID
+
+**Critical Distinction**:
+
+- `id`: MongoDB ObjectId (used internally)
+- `tenantId`: String identifier (used in API calls and display)
+
+**Usage**:
+
+```typescript
+// For GraphQL mutations/queries
+variables: {
+    id: tenant.tenantId;
+}
+
+// For display and internal references
+tenant.id; // MongoDB ID
+tenant.tenantId; // Tenant identifier
+```
+
+### 2. Secret Key Management
+
+**Important Behaviors**:
+
+- **Creation**: At least one secret key is required when creating a tenant
+- **Editing**: Existing keys are preserved; only new keys can be added
+- **Revealing**: Secret values are fetched on-demand (not stored in state)
+- **Revocation**: Permanent action; cannot be undone
+- **Security**: Secrets are hidden by default; must explicitly reveal
+
+**Best Practices**:
+
+- Never log secret values
+- Use one-time reveal pattern
+- Always confirm before revocation
+- Rotate keys regularly
+
+### 3. Form State Management
+
+**Key Points**:
+
+- Form state is managed in XState machine context
+- Field updates trigger machine events
+- Validation happens before submission
+- Form resets after successful operations
+
+**Form Data Structure**:
+
+```typescript
+{
+  name: string;
+  description: string;
+  environment: string | undefined; // Environment tag ID
+  projectId?: string; // Project ID
+  clientConfigurations: Array<{
+    name: string;
+    description?: string;
+  }>;
+}
+```
+
+### 4. Project and Environment Relationship
+
+**Workflow**:
+
+1. User selects a project
+2. System automatically fetches environment tags for that project
+3. First environment tag is auto-selected
+4. User can change environment if needed
+
+**Important**: Environment tags are project-specific. If no project is selected, environment selection may be limited.
+
+## Summary
+
+The Tenant Management System provides a comprehensive, user-friendly interface for managing multi-tenant configurations. It leverages modern React patterns, state management with XState, GraphQL for efficient data operations, and Inngest for asynchronous background processing. The system is designed with type safety, error handling, and user experience as top priorities.
+
+**Key Takeaways**:
+
+**Frontend**:
+
+- ✅ Full CRUD operations with proper state management
+- ✅ Secret key management with security best practices
+- ✅ Project and environment integration
+- ✅ Comprehensive error handling and user feedback
+- ✅ Type-safe implementation with TypeScript
+- ✅ Scalable architecture with XState and GraphQL
+
+**Backend**:
+
+- ✅ Event-driven architecture with Inngest for async operations
+- ✅ Keycloak integration for client management
+- ✅ Deterministic secret generation (no secret storage)
+- ✅ Status lifecycle management (Pending → Active/Error)
+- ✅ Retry mechanism for failed operations
+- ✅ Separation of concerns (Service handles DB, Inngest handles external APIs)