@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/architecture/multi-tenancy.mdx

@@ -0,0 +1,1150 @@
+---
+title: Multi-Tenancy Architecture
+description: Deep dive into the Blue Alba Platform multi-tenancy architecture - tenant isolation, context resolution, URL patterns, and data segregation
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The Blue Alba Platform is designed with **multi-tenancy** as a core architectural principle, enabling a single platform instance to serve multiple customers or organizations with complete data and configuration isolation.
+
+## Multi-Tenancy Overview
+
+Multi-tenancy allows the platform to:
+
+<CardGrid stagger>
+  <Card title="Serve Multiple Customers" icon="codeberg">
+    Run multiple isolated customer instances on shared infrastructure
+  </Card>
+
+  <Card title="Data Isolation" icon="seti:lock">
+    Complete segregation of tenant data at database and application levels
+  </Card>
+
+  <Card title="Custom Configuration" icon="setting">
+    Per-tenant settings, branding, and feature flags
+  </Card>
+
+  <Card title="Cost Efficiency" icon="rocket">
+    Shared infrastructure reduces operational costs
+  </Card>
+
+  <Card title="Simplified Operations" icon="seti:config">
+    Deploy once, serve many customers
+  </Card>
+
+  <Card title="Scalability" icon="star">
+    Add new tenants without infrastructure changes
+  </Card>
+</CardGrid>
+
+---
+
+## Tenant Entity
+
+### Tenant Structure
+
+```typescript
+interface Tenant {
+  id: string;                      // Unique identifier (UUID)
+  code: string;                    // Short code (e.g., "acme", "contoso")
+  name: string;                    // Display name (e.g., "ACME Corporation")
+  status: TenantStatus;            // ACTIVE | SUSPENDED | DELETED
+
+  // Configuration
+  config?: {
+    mode: 'SINGLE_TENANT' | 'MULTI_TENANT';
+    clientSideMode?: 'SUBDOMAIN' | 'PATH' | 'COOKIE' | 'SESSION_STORAGE' | 'QUERY_PARAM';
+    features?: Record<string, boolean>;
+    settings?: Record<string, any>;
+  };
+
+  // Branding
+  branding?: {
+    logo?: string;
+    favicon?: string;
+    primaryColor?: string;
+    secondaryColor?: string;
+    theme?: 'light' | 'dark';
+  };
+
+  // Subscription
+  plan?: string;
+  subscriptionStartDate?: Date;
+  subscriptionEndDate?: Date;
+  maxUsers?: number;
+
+  // Audit
+  createdAt: Date;
+  createdBy: string;
+  updatedAt: Date;
+  updatedBy: string;
+}
+
+type TenantStatus = 'ACTIVE' | 'SUSPENDED' | 'DELETED';
+```
+
+**Example**:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "code": "acme",
+  "name": "ACME Corporation",
+  "status": "ACTIVE",
+  "config": {
+    "mode": "MULTI_TENANT",
+    "clientSideMode": "SUBDOMAIN",
+    "features": {
+      "habits": true,
+      "scheduler": true,
+      "reports": false
+    }
+  },
+  "branding": {
+    "logo": "https://cdn.acme.com/logo.png",
+    "primaryColor": "#0066cc",
+    "secondaryColor": "#ff6600"
+  },
+  "plan": "enterprise",
+  "maxUsers": 500
+}
+```
+
+---
+
+## Tenant Modes
+
+The platform supports two tenant modes:
+
+<Tabs>
+  <TabItem label="SINGLE_TENANT">
+    **Single Tenant Mode**
+
+    - Platform serves a single organization
+    - No tenant resolution needed
+    - Simpler deployment and configuration
+    - Tenant context is fixed
+
+    ```typescript
+    const TENANT_CONFIG = {
+      mode: 'SINGLE_TENANT',
+      defaultTenantCode: 'acme'
+    };
+    ```
+
+    **Use Case**: Dedicated deployment for a single large customer
+  </TabItem>
+
+  <TabItem label="MULTI_TENANT">
+    **Multi-Tenant Mode**
+
+    - Platform serves multiple organizations
+    - Tenant must be resolved from request
+    - URL patterns, cookies, or headers identify tenant
+    - Full tenant isolation enforced
+
+    ```typescript
+    const TENANT_CONFIG = {
+      mode: 'MULTI_TENANT',
+      clientSideMode: 'SUBDOMAIN' // or PATH, COOKIE, etc.
+    };
+    ```
+
+    **Use Case**: SaaS deployment serving many customers
+  </TabItem>
+</Tabs>
+
+---
+
+## Tenant Context Resolution
+
+In multi-tenant mode, the gateway must determine which tenant is making the request.
+
+### Resolution Strategies
+
+The platform supports multiple strategies for tenant resolution:
+
+<Tabs>
+  <TabItem label="Subdomain">
+    **Subdomain-Based Resolution**
+
+    Extract tenant from subdomain:
+
+    ```
+    https://acme.platform.com     → tenant: "acme"
+    https://contoso.platform.com  → tenant: "contoso"
+    https://platform.com          → no tenant (login page)
+    ```
+
+    **Implementation**:
+
+    ```typescript
+    class SubdomainPatternMatcher implements TenantPatternMatcher {
+      async match(req: FastifyRequest): Promise<TenantContext | null> {
+        const host = req.headers.host; // "acme.platform.com"
+        const parts = host.split('.');
+
+        if (parts.length < 3) {
+          return null; // Not a subdomain
+        }
+
+        const subdomain = parts[0]; // "acme"
+
+        return {
+          type: 'SUBDOMAIN',
+          value: subdomain
+        };
+      }
+    }
+    ```
+
+    **Configuration**:
+
+    ```typescript
+    // Tenant URL pattern
+    {
+      tenantId: 'acme-tenant-id',
+      type: 'SUBDOMAIN',
+      pattern: 'acme.platform.com',
+      priority: 10
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Path">
+    **Path-Based Resolution**
+
+    Extract tenant from URL path:
+
+    ```
+    https://platform.com/tenants/acme/app     → tenant: "acme"
+    https://platform.com/t/contoso/dashboard  → tenant: "contoso"
+    https://platform.com/                     → no tenant
+    ```
+
+    **Implementation**:
+
+    ```typescript
+    class PathPatternMatcher implements TenantPatternMatcher {
+      async match(req: FastifyRequest): Promise<TenantContext | null> {
+        const url = req.url; // "/tenants/acme/app"
+
+        // Match pattern: /tenants/:tenantCode/*
+        const match = url.match(/^\/tenants\/([^\/]+)/);
+
+        if (!match) {
+          return null;
+        }
+
+        const tenantCode = match[1]; // "acme"
+
+        return {
+          type: 'PATH',
+          value: tenantCode
+        };
+      }
+    }
+    ```
+
+    **Configuration**:
+
+    ```typescript
+    {
+      tenantId: 'acme-tenant-id',
+      type: 'PATH',
+      pattern: '/tenants/acme/*',
+      priority: 10
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Custom Domain">
+    **Custom Domain Resolution**
+
+    Map entire domains to tenants:
+
+    ```
+    https://acme.com              → tenant: "acme"
+    https://www.acme.com          → tenant: "acme"
+    https://contoso.com           → tenant: "contoso"
+    ```
+
+    **Implementation**:
+
+    ```typescript
+    class CustomDomainPatternMatcher implements TenantPatternMatcher {
+      async match(req: FastifyRequest): Promise<TenantContext | null> {
+        const host = req.headers.host; // "acme.com"
+
+        // Normalize (remove www)
+        const domain = host.replace(/^www\./, '');
+
+        return {
+          type: 'CUSTOM_DOMAIN',
+          value: domain
+        };
+      }
+    }
+    ```
+
+    **Configuration**:
+
+    ```typescript
+    {
+      tenantId: 'acme-tenant-id',
+      type: 'CUSTOM_DOMAIN',
+      pattern: 'acme.com',
+      priority: 20  // Higher priority than subdomain
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Header">
+    **Header-Based Resolution**
+
+    Read tenant from custom header:
+
+    ```http
+    GET /api/data
+    Host: platform.com
+    x-tenant-id: acme
+    ```
+
+    **Implementation**:
+
+    ```typescript
+    class HeaderPatternMatcher implements TenantPatternMatcher {
+      async match(req: FastifyRequest): Promise<TenantContext | null> {
+        const tenantCode = req.headers['x-tenant-id'] as string;
+
+        if (!tenantCode) {
+          return null;
+        }
+
+        return {
+          type: 'HEADER',
+          value: tenantCode
+        };
+      }
+    }
+    ```
+
+    **Use Case**: Development, testing, API clients
+  </TabItem>
+
+  <TabItem label="Cookie">
+    **Cookie-Based Resolution**
+
+    Read tenant from cookie:
+
+    ```http
+    GET /api/data
+    Cookie: tenant=acme
+    ```
+
+    **Implementation**:
+
+    ```typescript
+    class CookiePatternMatcher implements TenantPatternMatcher {
+      async match(req: FastifyRequest): Promise<TenantContext | null> {
+        const tenantCode = req.cookies['tenant'];
+
+        if (!tenantCode) {
+          return null;
+        }
+
+        return {
+          type: 'COOKIE',
+          value: tenantCode
+        };
+      }
+    }
+    ```
+
+    **Use Case**: After tenant selection by user
+  </TabItem>
+
+  <TabItem label="Query Parameter">
+    **Query Parameter Resolution**
+
+    Read tenant from query string:
+
+    ```
+    https://platform.com?tenant=acme
+    https://platform.com/app?tenant=contoso
+    ```
+
+    **Implementation**:
+
+    ```typescript
+    class QueryParamPatternMatcher implements TenantPatternMatcher {
+      async match(req: FastifyRequest): Promise<TenantContext | null> {
+        const tenantCode = req.query.tenant as string;
+
+        if (!tenantCode) {
+          return null;
+        }
+
+        return {
+          type: 'QUERY_PARAM',
+          value: tenantCode
+        };
+      }
+    }
+    ```
+
+    **Use Case**: Development, testing, explicit tenant switching
+  </TabItem>
+</Tabs>
+
+### Resolution Priority
+
+Multiple patterns can be configured with priority levels. Higher priority patterns are checked first:
+
+```typescript
+const urlPatterns = [
+  { type: 'CUSTOM_DOMAIN', pattern: 'acme.com', priority: 100 },
+  { type: 'SUBDOMAIN', pattern: 'acme.platform.com', priority: 50 },
+  { type: 'PATH', pattern: '/tenants/acme/*', priority: 30 },
+  { type: 'HEADER', pattern: '*', priority: 20 },
+  { type: 'COOKIE', pattern: '*', priority: 10 },
+  { type: 'QUERY_PARAM', pattern: '*', priority: 5 }
+];
+
+// Sorted by priority (highest first)
+// Checked in order until a match is found
+```
+
+---
+
+## Tenant Resolution Flow
+
+```
+┌──────────┐
+│  Request │
+└────┬─────┘
+     │
+     ▼
+┌─────────────────────────────────────┐
+│  1. Extract Host/Path/Headers       │
+│     host: "acme.platform.com"       │
+│     path: "/api/orders"             │
+│     headers: { x-tenant: "acme" }   │
+└────┬────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────┐
+│  2. Get Tenant URL Patterns         │
+│     from database, sorted by        │
+│     priority                        │
+└────┬────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────┐
+│  3. Try Each Pattern Matcher        │
+│     - CustomDomainMatcher           │
+│     - SubdomainMatcher              │
+│     - PathMatcher                   │
+│     - HeaderMatcher                 │
+│     - CookieMatcher                 │
+│     - QueryParamMatcher             │
+└────┬────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────┐
+│  4. First Match Found?              │
+│     → TenantContext { type, value } │
+└────┬────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────┐
+│  5. Query Tenant by Context         │
+│     SELECT * FROM tenants           │
+│     WHERE code = 'acme'             │
+└────┬────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────┐
+│  6. Validate Tenant                 │
+│     - Status = ACTIVE?              │
+│     - User has access?              │
+│     - Subscription valid?           │
+└────┬────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────┐
+│  7. Store in Platform Context       │
+│     paeContext.setTenant(tenant)    │
+└─────────────────────────────────────┘
+```
+
+**Implementation**:
+
+```typescript
+// apps/pae-nestjs-gateway-service/src/tenants/tenant-resolver.service.ts
+
+@Injectable()
+export class TenantResolverService {
+  constructor(
+    @Inject('TENANT_STRATEGIES')
+    private readonly tenantStrategies: Record<string, TenantStrategy>,
+    private readonly tenantService: TenantsService,
+    private readonly parametersService: ParametersService
+  ) {}
+
+  async getTenantFromRequest(
+    request: FastifyRequest,
+    response: FastifyReply,
+    allowedTenants: Tenant[]
+  ): Promise<Tenant | null> {
+    // Get active strategies based on configuration
+    const strategies = await this.resolveStrategies(this.tenantStrategies);
+
+    // Try each strategy in order
+    for (const strategy of strategies) {
+      const tenantContext = await strategy.getTenantFromRequest(request);
+
+      if (tenantContext) {
+        // Found tenant context, look up tenant
+        const tenant = await this.tenantService.findTenantByContext(tenantContext);
+
+        if (tenant && allowedTenants.some(t => t.id === tenant.id)) {
+          // Valid tenant that user has access to
+          return tenant;
+        }
+      }
+    }
+
+    return null; // No tenant found
+  }
+}
+```
+
+---
+
+## Tenant Isolation
+
+### Database-Level Isolation
+
+All data tables include a `tenant_id` column for isolation:
+
+```sql
+-- Example: Orders table
+CREATE TABLE orders (
+  id UUID PRIMARY KEY,
+  tenant_id UUID NOT NULL REFERENCES tenants(id),
+  customer_id UUID NOT NULL,
+  total DECIMAL(10,2) NOT NULL,
+  status VARCHAR(50) NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW(),
+  -- ... other columns
+  CONSTRAINT fk_tenant FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
+);
+
+-- Index for fast tenant filtering
+CREATE INDEX idx_orders_tenant ON orders(tenant_id);
+
+-- All queries MUST filter by tenant_id
+SELECT * FROM orders WHERE tenant_id = :tenantId;
+```
+
+<Aside type="caution" title="Critical: Always Filter by Tenant">
+  **Every database query MUST include a `tenant_id` filter.** Failing to do so can expose data across tenant boundaries, which is a serious security breach. Use automated tests to verify tenant isolation.
+</Aside>
+
+### Application-Level Isolation
+
+Services automatically enforce tenant filtering:
+
+<Tabs>
+  <TabItem label="Automatic (Recommended)">
+    ```typescript
+    // Use platform context decorator
+    import { PlatformContext } from '@bluealba/pae-service-nestjs-sdk';
+
+    @Injectable()
+    export class OrdersService {
+      async findAll(@PlatformContext() ctx: PlatformContext) {
+        // Automatically filters by ctx.tenantId
+        return this.ordersRepository.find({
+          where: { tenantId: ctx.tenantId }
+        });
+      }
+
+      async findOne(id: string, @PlatformContext() ctx: PlatformContext) {
+        // Ensure order belongs to tenant
+        const order = await this.ordersRepository.findOne({
+          where: { id, tenantId: ctx.tenantId }
+        });
+
+        if (!order) {
+          throw new NotFoundException('Order not found');
+        }
+
+        return order;
+      }
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Manual (Advanced)">
+    ```typescript
+    // Explicitly pass tenant ID
+    @Injectable()
+    export class OrdersService {
+      async findAll(tenantId: string) {
+        return this.ordersRepository.find({
+          where: { tenantId }
+        });
+      }
+
+      async findOne(id: string, tenantId: string) {
+        const order = await this.ordersRepository.findOne({
+          where: { id, tenantId }
+        });
+
+        if (!order) {
+          throw new NotFoundException('Order not found');
+        }
+
+        return order;
+      }
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Query Builder">
+    ```typescript
+    // Using query builder (Knex)
+    @Injectable()
+    export class OrdersService {
+      async findAll(tenantId: string) {
+        return this.knex('orders')
+          .where('tenant_id', tenantId)
+          .select('*');
+      }
+
+      async create(data: CreateOrderDto, tenantId: string) {
+        const [order] = await this.knex('orders')
+          .insert({
+            ...data,
+            tenant_id: tenantId,  // Always include tenant_id
+            created_at: new Date()
+          })
+          .returning('*');
+
+        return order;
+      }
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+### Tenant Context Propagation
+
+The gateway adds tenant context to forwarded requests:
+
+```http
+POST /api/orders HTTP/1.1
+Host: orders-service:4001
+x-pae-user-id: john@acme.com
+x-pae-user: john@acme.com
+x-pae-tenant: eyJ0ZW5hbnRJZCI6ImFjbWUiLCAibmFtZSI6IkFDTUUgQ29ycCJ9
+x-pae-forwarded-tenant-config: eyJtb2RlIjoibXVsdGktdGVuYW50In0=
+
+{
+  "customerId": "cust-123",
+  "total": 99.99
+}
+```
+
+Services extract tenant context:
+
+```typescript
+// NestJS interceptor extracts and decodes headers
+@Injectable()
+export class TenantContextInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler) {
+    const request = context.switchToHttp().getRequest();
+
+    // Extract and decode tenant from header
+    const tenantHeader = request.headers['x-pae-tenant'];
+    const tenant = JSON.parse(base64Decode(tenantHeader));
+
+    // Store in request
+    request.tenant = tenant;
+    request.tenantId = tenant.id;
+
+    return next.handle();
+  }
+}
+```
+
+---
+
+## Tenant-Scoped Authorization Rules
+
+Authorization rules (the assignments of operations, roles, or applications to users and groups) are scoped to tenants via the `tenant_id` column in the `authz_rules` table.
+
+### How It Works
+
+- **Tenant-scoped rules** (`tenant_id` is set): Apply only within the specified tenant. All rules created from the Admin UI are automatically associated with the current tenant.
+- **Global rules** (`tenant_id` is `NULL`): Apply across all tenants. These are typically rules created before tenant scoping was introduced.
+
+When the authorization service evaluates permissions for a user, it includes:
+1. Rules that match the current tenant (`tenant_id = currentTenantId`)
+2. Global rules (`tenant_id IS NULL`)
+
+### Admin UI Behavior
+
+In multi-tenant mode, the Admin UI provides visual cues for tenant-scoped rules:
+
+- Rules without a `tenant_id` are displayed with a **"Global"** badge to indicate they apply across all tenants.
+- When **creating** new assignments, the current tenant is automatically associated.
+- When **removing** a global rule, a confirmation dialog warns that the deletion will affect all tenants.
+
+<Aside type="caution" title="Global Rule Deletion">
+  Deleting a global rule removes the assignment across **all** tenants. The Admin UI displays a confirmation warning before proceeding. Consider whether a tenant-scoped override is more appropriate.
+</Aside>
+
+---
+
+## Tenant-Scoped Applications
+
+Applications can be restricted to specific tenants.
+
+### Tenant Application Restrictions
+
+```typescript
+interface TenantApplicationRestriction {
+  id: string;
+  tenantId: string;
+  applicationId: string;
+  isRestricted: boolean;  // If true, app is BLOCKED for tenant
+  createdAt: Date;
+  createdBy: string;
+}
+```
+
+**Database**:
+
+```sql
+CREATE TABLE tenant_application_restrictions (
+  id UUID PRIMARY KEY,
+  tenant_id UUID NOT NULL REFERENCES tenants(id),
+  application_id INTEGER NOT NULL REFERENCES applications(id),
+  is_restricted BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP DEFAULT NOW(),
+  created_by VARCHAR(255) NOT NULL,
+  UNIQUE(tenant_id, application_id)
+);
+```
+
+**Usage**:
+
+```typescript
+// Check if tenant has access to application
+const hasAccess = await this.tenantApplicationRestrictionsService
+  .hasAccessToApplication(tenantId, applicationId);
+
+if (!hasAccess) {
+  throw new ForbiddenException('Application not available for this tenant');
+}
+
+// Filter catalog by tenant
+const catalog = await this.catalogService.getCatalog(tenantId);
+// Returns only applications tenant has access to
+```
+
+---
+
+## Tenant Route Restrictions
+
+Specific routes can be restricted per tenant.
+
+### Route Restriction Configuration
+
+```typescript
+interface TenantModuleRestriction {
+  id: string;
+  tenantId: string;
+  moduleId: string;
+  routePath: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | '*';
+  isBlocked: boolean;
+  reason?: string;
+  createdAt: Date;
+  createdBy: string;
+}
+```
+
+**Example**:
+
+```typescript
+// Block DELETE operations for tenant "acme"
+{
+  tenantId: 'acme-tenant-id',
+  moduleId: 'orders-service',
+  routePath: '/api/orders/:id',
+  method: 'DELETE',
+  isBlocked: true,
+  reason: 'Tenant plan does not include delete capability'
+}
+
+// Block entire analytics module
+{
+  tenantId: 'acme-tenant-id',
+  moduleId: 'analytics-service',
+  routePath: '*',
+  method: '*',
+  isBlocked: true,
+  reason: 'Analytics not included in tenant plan'
+}
+```
+
+**Enforcement**:
+
+```typescript
+// Gateway checks route restrictions
+const tenant = paeContext.getTenant();
+const targetModule = paeContext.getTargetModule();
+
+const isBlocked = await this.tenantRouteRestrictionsService
+  .isRouteBlocked(tenant.id, targetModule.id, req.url, req.method);
+
+if (isBlocked) {
+  throw new ForbiddenException('This route is not available for your tenant');
+}
+```
+
+---
+
+## Tenant Selection Flow
+
+For users with access to multiple tenants:
+
+```
+┌──────────┐
+│   User   │
+│  Logs In │
+└────┬─────┘
+     │
+     ▼
+┌─────────────────────────────────────┐
+│  1. Authenticate User               │
+│     Validate credentials            │
+└────┬────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────┐
+│  2. Query User's Allowed Tenants    │
+│     SELECT tenants FROM             │
+│     user_tenant_assignments         │
+│     WHERE user_id = :userId         │
+└────┬────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────┐
+│  3. How Many Tenants?               │
+├─────────────┬───────────────────────┤
+│   Single    │      Multiple         │
+└─────┬───────┴───────────┬───────────┘
+      │                   │
+      ▼                   ▼
+  ┌───────────┐    ┌──────────────────┐
+  │ Auto      │    │ Show Tenant      │
+  │ Select    │    │ Selection Screen │
+  └───┬───────┘    └────┬─────────────┘
+      │                 │
+      │                 ▼
+      │            ┌──────────────────┐
+      │            │ User Selects     │
+      │            │ Tenant           │
+      │            └────┬─────────────┘
+      │                 │
+      └────────┬────────┘
+               ▼
+      ┌─────────────────────────────────┐
+      │  4. Set Tenant Context          │
+      │     - Cookie                    │
+      │     - Session storage           │
+      │     - Redirect to subdomain     │
+      └─────┬───────────────────────────┘
+            │
+            ▼
+      ┌─────────────────────────────────┐
+      │  5. User Accesses Application   │
+      └─────────────────────────────────┘
+```
+
+**Frontend Implementation**:
+
+```typescript
+// React component for tenant selection
+function TenantSelectionPage() {
+  const [tenants, setTenants] = useState<Tenant[]>([]);
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    // Fetch user's allowed tenants
+    fetch('/api/me/tenants')
+      .then(res => res.json())
+      .then(data => setTenants(data));
+  }, []);
+
+  const selectTenant = async (tenant: Tenant) => {
+    // Set tenant cookie
+    document.cookie = `tenant=${tenant.code}; path=/; secure; samesite=lax`;
+
+    // Or redirect to tenant subdomain
+    window.location.href = `https://${tenant.code}.platform.com`;
+  };
+
+  return (
+    <div>
+      <h1>Select Organization</h1>
+      {tenants.map(tenant => (
+        <button key={tenant.id} onClick={() => selectTenant(tenant)}>
+          {tenant.name}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## Tenant Provisioning
+
+### Creating a New Tenant
+
+```typescript
+@Post('tenants')
+async createTenant(
+  @Body() dto: CreateTenantDto,
+  @User() user: AuthUserWithApplications
+) {
+  // 1. Create tenant record
+  const tenant = await this.tenantsService.create({
+    code: dto.code,
+    name: dto.name,
+    status: 'ACTIVE',
+    config: {
+      mode: 'MULTI_TENANT',
+      clientSideMode: 'SUBDOMAIN'
+    },
+    createdBy: user.username
+  });
+
+  // 2. Create URL patterns
+  await this.tenantUrlPatternsService.create({
+    tenantId: tenant.id,
+    type: 'SUBDOMAIN',
+    pattern: `${dto.code}.platform.com`,
+    priority: 50
+  });
+
+  // 3. Assign default applications
+  const defaultApps = await this.applicationsService.findDefaultApps();
+  for (const app of defaultApps) {
+    await this.tenantApplicationRestrictionsService.create({
+      tenantId: tenant.id,
+      applicationId: app.id,
+      isRestricted: false
+    });
+  }
+
+  // 4. Create admin user for tenant
+  await this.usersService.create({
+    email: dto.adminEmail,
+    displayName: dto.adminName,
+    tenantId: tenant.id,
+    roles: ['admin']
+  });
+
+  // 5. Provision IDP (Okta, EntraId, etc.)
+  if (dto.provisionIDP) {
+    await this.idpProvisioningService.provisionTenant(tenant);
+  }
+
+  return tenant;
+}
+```
+
+---
+
+## Configuration Management
+
+### Tenant-Specific Configuration
+
+```typescript
+// Get tenant configuration
+const config = await this.tenantsService.getConfig(tenantId);
+
+// Check feature flags
+if (config.features?.habits === true) {
+  // Habits feature enabled for this tenant
+}
+
+// Get custom settings
+const maxFileSize = config.settings?.maxFileUploadSize || 10 * 1024 * 1024;
+```
+
+### Configuration Hierarchy
+
+```
+1. Global Configuration (platform-wide defaults)
+   ↓
+2. Tenant Configuration (tenant-specific overrides)
+   ↓
+3. User Configuration (user preferences)
+```
+
+**Example**:
+
+```typescript
+// Get effective configuration value
+function getConfigValue(key: string, tenantId?: string, userId?: string): any {
+  // 1. Try user config
+  if (userId) {
+    const userConfig = getUserConfig(userId);
+    if (userConfig[key] !== undefined) {
+      return userConfig[key];
+    }
+  }
+
+  // 2. Try tenant config
+  if (tenantId) {
+    const tenantConfig = getTenantConfig(tenantId);
+    if (tenantConfig[key] !== undefined) {
+      return tenantConfig[key];
+    }
+  }
+
+  // 3. Fall back to global config
+  return getGlobalConfig(key);
+}
+```
+
+---
+
+## Testing Tenant Isolation
+
+### Unit Tests
+
+```typescript
+describe('OrdersService', () => {
+  it('should only return orders for specified tenant', async () => {
+    // Arrange
+    const tenant1Id = 'tenant-1';
+    const tenant2Id = 'tenant-2';
+
+    await ordersRepository.create({ id: '1', tenantId: tenant1Id, total: 100 });
+    await ordersRepository.create({ id: '2', tenantId: tenant2Id, total: 200 });
+    await ordersRepository.create({ id: '3', tenantId: tenant1Id, total: 300 });
+
+    // Act
+    const orders = await ordersService.findAll(tenant1Id);
+
+    // Assert
+    expect(orders).toHaveLength(2);
+    expect(orders.every(o => o.tenantId === tenant1Id)).toBe(true);
+  });
+
+  it('should throw error when accessing other tenant data', async () => {
+    // Arrange
+    const tenant1Id = 'tenant-1';
+    const tenant2Id = 'tenant-2';
+
+    const order = await ordersRepository.create({
+      id: '1',
+      tenantId: tenant1Id,
+      total: 100
+    });
+
+    // Act & Assert
+    await expect(
+      ordersService.findOne(order.id, tenant2Id)
+    ).rejects.toThrow('Order not found');
+  });
+});
+```
+
+### Integration Tests
+
+```typescript
+describe('Orders API (E2E)', () => {
+  it('should enforce tenant isolation', async () => {
+    // Create two tenants
+    const tenant1 = await createTenant('acme');
+    const tenant2 = await createTenant('contoso');
+
+    // Create user for tenant1
+    const user1Token = await authenticateUser('user1@acme.com', tenant1.id);
+
+    // Create order for tenant1
+    const order = await request(app.getHttpServer())
+      .post('/api/orders')
+      .set('Cookie', `auth_token=${user1Token}`)
+      .set('x-tenant-id', 'acme')
+      .send({ total: 100 })
+      .expect(201);
+
+    // Try to access order from tenant2 context
+    const user2Token = await authenticateUser('user2@contoso.com', tenant2.id);
+
+    await request(app.getHttpServer())
+      .get(`/api/orders/${order.body.id}`)
+      .set('Cookie', `auth_token=${user2Token}`)
+      .set('x-tenant-id', 'contoso')
+      .expect(404); // Should not find order
+  });
+});
+```
+
+---
+
+## Security Considerations
+
+<Aside type="caution" title="Multi-Tenancy Security Best Practices">
+
+**Tenant Isolation**:
+- ALWAYS filter database queries by `tenant_id`
+- NEVER trust client-provided tenant identifiers
+- Validate tenant context on every request
+- Use foreign key constraints to enforce database-level isolation
+
+**Data Leakage Prevention**:
+- Test tenant isolation extensively
+- Implement automated tests for cross-tenant access
+- Use database views or row-level security (RLS) for additional protection
+- Audit logs should include tenant context
+
+**Tenant Context Validation**:
+- Verify user has access to requested tenant
+- Check tenant status (ACTIVE vs SUSPENDED)
+- Validate subscription and feature access
+- Handle tenant switching carefully
+
+**Performance**:
+- Index `tenant_id` columns for fast filtering
+- Consider partitioning large tables by tenant
+- Cache tenant configuration appropriately
+- Monitor query performance per tenant
+
+**Compliance**:
+- Support data residency requirements per tenant
+- Enable per-tenant data export and deletion
+- Maintain audit trails per tenant
+- Support tenant-specific retention policies
+
+</Aside>
+
+---
+
+## Next Steps
+
+- **[Gateway Architecture](/_/docs/architecture/gateway-architecture/)** - How gateway manages tenant context
+- **[Authentication System](/_/docs/architecture/authentication-system/)** - Tenant-aware authentication
+- **[Authorization System](/_/docs/architecture/authorization-system/)** - Tenant-scoped authorization