MongoDB Multi-Tenant Database Design and Schema Architecture: Advanced Patterns for Scalable SaaS Applications

-- Traditional single-tenant approach - separate database per tenant (expensive and complex)

-- Tenant 1 Database
CREATE DATABASE tenant_1_app_db;
USE tenant_1_app_db;

CREATE TABLE customers (
    customer_id SERIAL PRIMARY KEY,
    company_name VARCHAR(255) NOT NULL,
    contact_email VARCHAR(255) NOT NULL,
    subscription_plan VARCHAR(50) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    -- Single-tenant specific fields
    tenant_id VARCHAR(100) NOT NULL DEFAULT 'tenant_1',
    tenant_config JSON,
    custom_fields JSON
);

CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INTEGER REFERENCES customers(customer_id),
    order_total DECIMAL(10,2) NOT NULL,
    order_status VARCHAR(50) NOT NULL,
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    -- Tenant-specific customizations
    tenant_id VARCHAR(100) NOT NULL DEFAULT 'tenant_1',
    tenant_workflow_stage VARCHAR(100),
    custom_order_fields JSON
);

CREATE TABLE products (
    product_id SERIAL PRIMARY KEY,
    product_name VARCHAR(255) NOT NULL,
    product_sku VARCHAR(100) UNIQUE NOT NULL,
    product_price DECIMAL(10,2) NOT NULL,
    inventory_count INTEGER DEFAULT 0,

    -- Tenant-specific product data
    tenant_id VARCHAR(100) NOT NULL DEFAULT 'tenant_1',
    tenant_product_categories TEXT[],
    custom_product_fields JSON
);

-- Tenant 2 Database (identical structure - resource duplication)
CREATE DATABASE tenant_2_app_db;
USE tenant_2_app_db;

-- Duplicate all table definitions with different tenant_id defaults
CREATE TABLE customers (
    customer_id SERIAL PRIMARY KEY,
    company_name VARCHAR(255) NOT NULL,
    contact_email VARCHAR(255) NOT NULL,
    subscription_plan VARCHAR(50) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    tenant_id VARCHAR(100) NOT NULL DEFAULT 'tenant_2',
    tenant_config JSON,
    custom_fields JSON
);

-- ... repeat for orders, products, etc.

-- Problems with single-tenant database approach:
-- 1. Massive resource duplication - each tenant needs full database infrastructure
-- 2. Complex backup and maintenance operations across hundreds of databases
-- 3. Inefficient resource utilization - small tenants waste allocated resources
-- 4. Expensive database licensing and infrastructure costs
-- 5. Difficult cross-tenant analytics and reporting
-- 6. Complex application deployment and configuration management
-- 7. Challenging schema evolution across multiple databases
-- 8. Poor resource sharing and peak load distribution
-- 9. Complex monitoring and performance optimization
-- 10. Difficult disaster recovery and data migration scenarios

-- Example of complex connection management for single-tenant approach
-- Application code must maintain separate connections per tenant

-- PostgreSQL connection configuration for single-tenant (complex management)
CREATE ROLE tenant_1_user WITH LOGIN PASSWORD 'secure_password_1';
GRANT ALL PRIVILEGES ON DATABASE tenant_1_app_db TO tenant_1_user;

CREATE ROLE tenant_2_user WITH LOGIN PASSWORD 'secure_password_2';
GRANT ALL PRIVILEGES ON DATABASE tenant_2_app_db TO tenant_2_user;

-- Application must manage multiple connection pools
-- Connection Pool Configuration (simplified example):
-- tenant_1_pool: max_connections=20, database=tenant_1_app_db, user=tenant_1_user
-- tenant_2_pool: max_connections=20, database=tenant_2_app_db, user=tenant_2_user
-- tenant_n_pool: max_connections=20, database=tenant_n_app_db, user=tenant_n_user

-- Query execution requires tenant-specific connection routing
SELECT c.company_name, COUNT(o.order_id) as order_count
FROM customers c
LEFT JOIN orders o ON c.customer_id = o.customer_id
WHERE c.created_at >= CURRENT_DATE - INTERVAL '30 days'
GROUP BY c.company_name;

-- This query must be executed separately for each tenant database:
-- - Connect to tenant_1_app_db and execute query
-- - Connect to tenant_2_app_db and execute query  
-- - Connect to tenant_n_app_db and execute query
-- - Aggregate results at application level (complex)

-- Schema evolution challenges in single-tenant approach
-- Adding a new field requires coordinated deployment across all tenant databases

-- Add new field to customers table (must be done for EVERY tenant database)
ALTER TABLE customers ADD COLUMN subscription_renewal_date DATE;
ALTER TABLE customers ADD COLUMN billing_cycle VARCHAR(20) DEFAULT 'monthly';

-- Must be executed for:
-- tenant_1_app_db.customers
-- tenant_2_app_db.customers  
-- tenant_3_app_db.customers
-- ... tenant_n_app_db.customers

-- Backup and recovery complexity
-- Individual backup strategies per tenant database
pg_dump tenant_1_app_db > tenant_1_backup_2025_12_17.sql
pg_dump tenant_2_app_db > tenant_2_backup_2025_12_17.sql
pg_dump tenant_3_app_db > tenant_3_backup_2025_12_17.sql
-- ... repeat for all tenant databases

-- Cross-tenant reporting challenges (requires complex federation)
-- Attempting to get aggregate statistics across all tenants
WITH tenant_1_data AS (
    SELECT 'tenant_1' as tenant_id, COUNT(*) as customer_count, SUM(order_total) as revenue
    FROM tenant_1_app_db.customers c
    LEFT JOIN tenant_1_app_db.orders o ON c.customer_id = o.customer_id
),
tenant_2_data AS (
    SELECT 'tenant_2' as tenant_id, COUNT(*) as customer_count, SUM(order_total) as revenue
    FROM tenant_2_app_db.customers c
    LEFT JOIN tenant_2_app_db.orders o ON c.customer_id = o.customer_id
)
-- This approach becomes impossible with many tenants and requires complex application-level aggregation

-- Single-tenant limitations:
-- 1. Prohibitive infrastructure costs for large numbers of tenants
-- 2. Complex operational overhead for database maintenance
-- 3. Poor resource utilization and sharing inefficiencies
-- 4. Difficult cross-tenant feature development and analytics
-- 5. Complex disaster recovery and business continuity planning
-- 6. Challenging performance monitoring and optimization across databases
-- 7. Inefficient development and testing environment management
-- 8. Complex compliance and audit trail management
-- 9. Difficult tenant onboarding and offboarding processes
-- 10. Poor scalability characteristics for SaaS growth patterns

// MongoDB Advanced Multi-Tenant Database Design and Schema Architecture

const { MongoClient, ObjectId } = require('mongodb');

// Comprehensive Multi-Tenant Database Architecture Manager
class MongoDBMultiTenantManager {
  constructor(connectionString, config = {}) {
    this.client = new MongoClient(connectionString);
    this.db = null;

    // Multi-tenant configuration strategies
    this.tenantStrategy = config.tenantStrategy || 'shared_database_shared_collection'; // Options: shared_database_shared_collection, shared_database_separate_collections, separate_databases
    this.tenantIsolationLevel = config.tenantIsolationLevel || 'logical'; // Options: logical, physical, hybrid
    this.enableTenantSharding = config.enableTenantSharding || false;
    this.enableTenantReplication = config.enableTenantReplication || false;

    // Advanced multi-tenant features
    this.config = {
      // Tenant identification and routing
      tenantIdentification: {
        strategy: config.tenantIdStrategy || 'header', // header, subdomain, path, database
        fieldName: config.tenantIdField || 'tenant_id',
        enableTenantCaching: config.enableTenantCaching !== false,
        cacheExpiration: config.cacheExpiration || 300000 // 5 minutes
      },

      // Data isolation and security
      dataIsolation: {
        enableRowLevelSecurity: config.enableRowLevelSecurity !== false,
        enableEncryptionAtRest: config.enableEncryptionAtRest || false,
        enableFieldLevelEncryption: config.enableFieldLevelEncryption || false,
        enableAuditLogging: config.enableAuditLogging !== false
      },

      // Performance and scalability
      performance: {
        enableTenantIndexing: config.enableTenantIndexing !== false,
        enableQueryOptimization: config.enableQueryOptimization !== false,
        enableCaching: config.enableCaching !== false,
        enableConnectionPooling: config.enableConnectionPooling !== false
      },

      // Schema management and evolution
      schemaManagement: {
        enableFlexibleSchemas: config.enableFlexibleSchemas !== false,
        enableSchemaVersioning: config.enableSchemaVersioning || false,
        enableCustomFields: config.enableCustomFields !== false,
        enableTenantSpecificCollections: config.enableTenantSpecificCollections || false
      },

      // Resource management
      resourceManagement: {
        enableResourceQuotas: config.enableResourceQuotas || false,
        enableTenantMetrics: config.enableTenantMetrics !== false,
        enableAutoScaling: config.enableAutoScaling || false,
        enableLoadBalancing: config.enableLoadBalancing || false
      }
    };

    this.tenantRegistry = new Map();
    this.tenantMetrics = new Map();
    this.initializeMultiTenantArchitecture();
  }

  async initializeMultiTenantArchitecture() {
    console.log('Initializing MongoDB multi-tenant architecture...');

    try {
      await this.client.connect();
      this.db = this.client.db('multi_tenant_saas_platform');

      // Setup tenant registry and metadata management
      await this.setupTenantRegistry();

      // Configure multi-tenant collections and indexes
      await this.setupMultiTenantCollections();

      // Initialize tenant-aware security and access control
      await this.setupTenantSecurity();

      // Setup performance monitoring and optimization
      await this.setupTenantPerformanceMonitoring();

      console.log('Multi-tenant architecture initialized successfully');

    } catch (error) {
      console.error('Error initializing multi-tenant architecture:', error);
      throw error;
    }
  }

  async setupTenantRegistry() {
    console.log('Setting up tenant registry and metadata management...');

    const tenantRegistry = this.db.collection('tenant_registry');

    // Create indexes for efficient tenant lookup and management
    await tenantRegistry.createIndex({ tenant_id: 1 }, { unique: true });
    await tenantRegistry.createIndex({ subdomain: 1 }, { unique: true, sparse: true });
    await tenantRegistry.createIndex({ status: 1, created_at: -1 });
    await tenantRegistry.createIndex({ subscription_plan: 1, tenant_tier: 1 });

    // Setup tenant metadata collection for configuration and customization
    const tenantMetadata = this.db.collection('tenant_metadata');
    await tenantMetadata.createIndex({ tenant_id: 1, metadata_type: 1 }, { unique: true });
    await tenantMetadata.createIndex({ tenant_id: 1, updated_at: -1 });
  }

  async setupMultiTenantCollections() {
    console.log('Setting up multi-tenant collections and schema architecture...');

    // Setup shared collections with tenant isolation
    const collections = ['customers', 'orders', 'products', 'invoices', 'users', 'analytics_events'];

    for (const collectionName of collections) {
      const collection = this.db.collection(collectionName);

      // Create tenant-aware indexes for optimal performance and isolation
      await collection.createIndex({ tenant_id: 1 });
      await collection.createIndex({ tenant_id: 1, created_at: -1 });
      await collection.createIndex({ tenant_id: 1, updated_at: -1 });

      // Collection-specific indexes
      if (collectionName === 'customers') {
        await collection.createIndex({ tenant_id: 1, email: 1 }, { unique: true });
        await collection.createIndex({ tenant_id: 1, company_name: 1 });
        await collection.createIndex({ tenant_id: 1, subscription_status: 1 });
      } else if (collectionName === 'orders') {
        await collection.createIndex({ tenant_id: 1, customer_id: 1, order_date: -1 });
        await collection.createIndex({ tenant_id: 1, order_status: 1, order_date: -1 });
        await collection.createIndex({ tenant_id: 1, order_total: -1 });
      } else if (collectionName === 'products') {
        await collection.createIndex({ tenant_id: 1, sku: 1 }, { unique: true });
        await collection.createIndex({ tenant_id: 1, category: 1, name: 1 });
        await collection.createIndex({ tenant_id: 1, price: 1, inventory_count: 1 });
      }
    }

    // Setup tenant-specific collections for high isolation requirements
    if (this.config.schemaManagement.enableTenantSpecificCollections) {
      await this.setupTenantSpecificCollections();
    }
  }

  async setupTenantSecurity() {
    console.log('Setting up tenant-aware security and access control...');

    // Create tenant-specific users and roles for enhanced security
    const tenantSecurity = this.db.collection('tenant_security');

    await tenantSecurity.createIndex({ tenant_id: 1, user_id: 1 }, { unique: true });
    await tenantSecurity.createIndex({ tenant_id: 1, role: 1 });
    await tenantSecurity.createIndex({ tenant_id: 1, permissions: 1 });

    // Setup audit logging for tenant data access
    if (this.config.dataIsolation.enableAuditLogging) {
      const auditLog = this.db.collection('tenant_audit_log');
      await auditLog.createIndex({ tenant_id: 1, timestamp: -1 });
      await auditLog.createIndex({ tenant_id: 1, action: 1, timestamp: -1 });
      await auditLog.createIndex({ tenant_id: 1, user_id: 1, timestamp: -1 });
    }
  }

  async setupTenantPerformanceMonitoring() {
    console.log('Setting up tenant performance monitoring and metrics...');

    const performanceMetrics = this.db.collection('tenant_performance_metrics');

    await performanceMetrics.createIndex({ tenant_id: 1, timestamp: -1 });
    await performanceMetrics.createIndex({ tenant_id: 1, metric_type: 1, timestamp: -1 });
    await performanceMetrics.createIndex({ tenant_id: 1, collection_name: 1, timestamp: -1 });

    // Setup resource usage tracking
    const resourceUsage = this.db.collection('tenant_resource_usage');
    await resourceUsage.createIndex({ tenant_id: 1, date: -1 });
    await resourceUsage.createIndex({ tenant_id: 1, resource_type: 1, date: -1 });
  }

  // Tenant registration and onboarding
  async registerNewTenant(tenantData) {
    console.log(`Registering new tenant: ${tenantData.tenant_id}`);

    try {
      const tenantRegistry = this.db.collection('tenant_registry');

      // Validate tenant data and check for conflicts
      const existingTenant = await tenantRegistry.findOne({ 
        $or: [
          { tenant_id: tenantData.tenant_id },
          { subdomain: tenantData.subdomain },
          { primary_domain: tenantData.primary_domain }
        ]
      });

      if (existingTenant) {
        throw new Error(`Tenant with identifier already exists: ${tenantData.tenant_id}`);
      }

      // Create comprehensive tenant registration
      const tenantRegistration = {
        tenant_id: tenantData.tenant_id,
        tenant_name: tenantData.tenant_name,
        subdomain: tenantData.subdomain,
        primary_domain: tenantData.primary_domain,

        // Tenant configuration
        configuration: {
          tenant_tier: tenantData.tenant_tier || 'standard',
          subscription_plan: tenantData.subscription_plan || 'basic',
          max_users: tenantData.max_users || 10,
          max_storage_gb: tenantData.max_storage_gb || 5,
          max_monthly_requests: tenantData.max_monthly_requests || 10000,

          // Feature flags
          features: {
            enable_advanced_analytics: tenantData.enable_advanced_analytics || false,
            enable_custom_branding: tenantData.enable_custom_branding || false,
            enable_api_access: tenantData.enable_api_access || true,
            enable_webhooks: tenantData.enable_webhooks || false,
            enable_sso: tenantData.enable_sso || false
          },

          // Data retention and compliance
          data_retention: {
            retention_period_days: tenantData.retention_period_days || 365,
            enable_gdpr_compliance: tenantData.enable_gdpr_compliance || false,
            enable_audit_trail: tenantData.enable_audit_trail || true
          }
        },

        // Tenant status and metadata
        status: 'active',
        created_at: new Date(),
        updated_at: new Date(),

        // Contact and billing information
        contact_info: {
          admin_email: tenantData.admin_email,
          billing_email: tenantData.billing_email || tenantData.admin_email,
          support_contact: tenantData.support_contact
        },

        // Technical configuration
        technical_config: {
          database_strategy: this.tenantStrategy,
          isolation_level: this.tenantIsolationLevel,
          enable_sharding: tenantData.enable_sharding || false,
          enable_replication: tenantData.enable_replication || true,
          preferred_read_region: tenantData.preferred_read_region || 'us-east-1'
        }
      };

      // Insert tenant registration
      const registrationResult = await tenantRegistry.insertOne(tenantRegistration);

      // Initialize tenant-specific collections and indexes
      await this.initializeTenantResources(tenantData.tenant_id);

      // Create initial tenant metadata
      await this.createTenantMetadata(tenantData.tenant_id, {
        schema_version: '1.0.0',
        custom_fields: tenantData.custom_fields || {},
        ui_configuration: tenantData.ui_configuration || {},
        integration_settings: tenantData.integration_settings || {}
      });

      // Update tenant registry cache
      this.tenantRegistry.set(tenantData.tenant_id, tenantRegistration);

      console.log(`Tenant ${tenantData.tenant_id} registered successfully`);
      return {
        success: true,
        tenant_id: tenantData.tenant_id,
        registration_id: registrationResult.insertedId,
        tenant_config: tenantRegistration.configuration
      };

    } catch (error) {
      console.error(`Error registering tenant ${tenantData.tenant_id}:`, error);
      throw error;
    }
  }

  async initializeTenantResources(tenantId) {
    console.log(`Initializing resources for tenant: ${tenantId}`);

    // Create initial tenant data and sample records
    const collections = ['customers', 'orders', 'products', 'users'];

    for (const collectionName of collections) {
      const collection = this.db.collection(collectionName);

      // Initialize with tenant-specific welcome data
      if (collectionName === 'users') {
        await collection.insertOne({
          tenant_id: tenantId,
          user_id: 'admin',
          username: 'admin',
          email: 'admin@' + tenantId + '.com',
          role: 'tenant_admin',
          permissions: ['read', 'write', 'admin'],
          created_at: new Date(),
          updated_at: new Date(),
          status: 'active',
          profile: {
            first_name: 'Tenant',
            last_name: 'Administrator',
            timezone: 'UTC',
            language: 'en',
            theme: 'light'
          }
        });
      }
    }

    // Initialize tenant metrics tracking
    this.tenantMetrics.set(tenantId, {
      total_documents: 0,
      storage_usage_bytes: 0,
      monthly_requests: 0,
      last_activity: new Date(),
      performance_metrics: {
        avg_query_time_ms: 0,
        avg_throughput_ops_per_sec: 0
      }
    });
  }

  async createTenantMetadata(tenantId, metadata) {
    const tenantMetadata = this.db.collection('tenant_metadata');

    const metadataDocument = {
      tenant_id: tenantId,
      metadata_type: 'configuration',
      metadata: metadata,
      created_at: new Date(),
      updated_at: new Date(),
      version: 1
    };

    return await tenantMetadata.insertOne(metadataDocument);
  }

  // Advanced tenant data operations with isolation
  async insertTenantDocument(tenantId, collectionName, document, options = {}) {
    console.log(`Inserting document for tenant ${tenantId} into ${collectionName}`);

    try {
      // Validate tenant access
      await this.validateTenantAccess(tenantId);

      const collection = this.db.collection(collectionName);

      // Ensure tenant isolation
      const tenantDocument = {
        ...document,
        tenant_id: tenantId,
        created_at: new Date(),
        updated_at: new Date(),

        // Add tenant-specific metadata
        tenant_metadata: {
          created_by_tenant: tenantId,
          tenant_schema_version: await this.getTenantSchemaVersion(tenantId),
          isolation_level: this.tenantIsolationLevel
        }
      };

      // Apply tenant-specific validation and business rules
      await this.validateTenantDocument(tenantId, collectionName, tenantDocument);

      const result = await collection.insertOne(tenantDocument, options);

      // Update tenant metrics
      await this.updateTenantMetrics(tenantId, 'document_inserted', { collection: collectionName });

      // Log tenant activity
      if (this.config.dataIsolation.enableAuditLogging) {
        await this.logTenantActivity(tenantId, 'insert', {
          collection: collectionName,
          document_id: result.insertedId,
          timestamp: new Date()
        });
      }

      return result;

    } catch (error) {
      console.error(`Error inserting document for tenant ${tenantId}:`, error);
      throw error;
    }
  }

  async queryTenantDocuments(tenantId, collectionName, query = {}, options = {}) {
    console.log(`Querying documents for tenant ${tenantId} from ${collectionName}`);

    try {
      // Validate tenant access
      await this.validateTenantAccess(tenantId);

      const collection = this.db.collection(collectionName);

      // Ensure tenant isolation in query
      const tenantQuery = {
        tenant_id: tenantId,
        ...query
      };

      // Apply tenant-specific query optimizations
      const optimizedOptions = await this.optimizeTenantQuery(tenantId, options);

      const startTime = Date.now();
      const results = await collection.find(tenantQuery, optimizedOptions).toArray();
      const queryTime = Date.now() - startTime;

      // Update tenant performance metrics
      await this.updateTenantMetrics(tenantId, 'query_executed', { 
        collection: collectionName,
        query_time_ms: queryTime,
        documents_returned: results.length
      });

      // Log tenant query activity
      if (this.config.dataIsolation.enableAuditLogging) {
        await this.logTenantActivity(tenantId, 'query', {
          collection: collectionName,
          query: tenantQuery,
          results_count: results.length,
          query_time_ms: queryTime,
          timestamp: new Date()
        });
      }

      return results;

    } catch (error) {
      console.error(`Error querying documents for tenant ${tenantId}:`, error);
      throw error;
    }
  }

  async updateTenantDocuments(tenantId, collectionName, filter, update, options = {}) {
    console.log(`Updating documents for tenant ${tenantId} in ${collectionName}`);

    try {
      await this.validateTenantAccess(tenantId);

      const collection = this.db.collection(collectionName);

      // Ensure tenant isolation in filter
      const tenantFilter = {
        tenant_id: tenantId,
        ...filter
      };

      // Add tenant-specific update metadata
      const tenantUpdate = {
        ...update,
        $set: {
          ...update.$set,
          updated_at: new Date(),
          updated_by_tenant: tenantId
        }
      };

      const result = await collection.updateMany(tenantFilter, tenantUpdate, options);

      // Update tenant metrics
      await this.updateTenantMetrics(tenantId, 'documents_updated', { 
        collection: collectionName,
        documents_modified: result.modifiedCount
      });

      // Log tenant update activity
      if (this.config.dataIsolation.enableAuditLogging) {
        await this.logTenantActivity(tenantId, 'update', {
          collection: collectionName,
          filter: tenantFilter,
          update: tenantUpdate,
          documents_modified: result.modifiedCount,
          timestamp: new Date()
        });
      }

      return result;

    } catch (error) {
      console.error(`Error updating documents for tenant ${tenantId}:`, error);
      throw error;
    }
  }

  async deleteTenantDocuments(tenantId, collectionName, filter, options = {}) {
    console.log(`Deleting documents for tenant ${tenantId} from ${collectionName}`);

    try {
      await this.validateTenantAccess(tenantId);

      const collection = this.db.collection(collectionName);

      // Ensure tenant isolation in filter
      const tenantFilter = {
        tenant_id: tenantId,
        ...filter
      };

      const result = await collection.deleteMany(tenantFilter, options);

      // Update tenant metrics
      await this.updateTenantMetrics(tenantId, 'documents_deleted', { 
        collection: collectionName,
        documents_deleted: result.deletedCount
      });

      // Log tenant delete activity
      if (this.config.dataIsolation.enableAuditLogging) {
        await this.logTenantActivity(tenantId, 'delete', {
          collection: collectionName,
          filter: tenantFilter,
          documents_deleted: result.deletedCount,
          timestamp: new Date()
        });
      }

      return result;

    } catch (error) {
      console.error(`Error deleting documents for tenant ${tenantId}:`, error);
      throw error;
    }
  }

  // Advanced tenant analytics and reporting
  async generateTenantAnalytics(tenantId, timeRange = '30d') {
    console.log(`Generating analytics for tenant ${tenantId} for ${timeRange}`);

    try {
      await this.validateTenantAccess(tenantId);

      const endDate = new Date();
      const startDate = new Date();

      switch (timeRange) {
        case '24h':
          startDate.setDate(endDate.getDate() - 1);
          break;
        case '7d':
          startDate.setDate(endDate.getDate() - 7);
          break;
        case '30d':
          startDate.setDate(endDate.getDate() - 30);
          break;
        case '90d':
          startDate.setDate(endDate.getDate() - 90);
          break;
      }

      const analytics = {
        tenant_id: tenantId,
        time_range: timeRange,
        generated_at: new Date(),

        // Document counts across collections
        document_counts: await this.getTenantDocumentCounts(tenantId),

        // Growth metrics
        growth_metrics: await this.getTenantGrowthMetrics(tenantId, startDate, endDate),

        // Activity metrics
        activity_metrics: await this.getTenantActivityMetrics(tenantId, startDate, endDate),

        // Performance metrics
        performance_metrics: await this.getTenantPerformanceMetrics(tenantId, startDate, endDate),

        // Resource utilization
        resource_usage: await this.getTenantResourceUsage(tenantId, startDate, endDate)
      };

      return analytics;

    } catch (error) {
      console.error(`Error generating analytics for tenant ${tenantId}:`, error);
      throw error;
    }
  }

  async getTenantDocumentCounts(tenantId) {
    const collections = ['customers', 'orders', 'products', 'users'];
    const counts = {};

    for (const collectionName of collections) {
      const collection = this.db.collection(collectionName);
      counts[collectionName] = await collection.countDocuments({ tenant_id: tenantId });
    }

    return counts;
  }

  async getTenantGrowthMetrics(tenantId, startDate, endDate) {
    const collections = ['customers', 'orders'];
    const growth = {};

    for (const collectionName of collections) {
      const collection = this.db.collection(collectionName);

      const totalCount = await collection.countDocuments({ tenant_id: tenantId });
      const periodCount = await collection.countDocuments({
        tenant_id: tenantId,
        created_at: { $gte: startDate, $lte: endDate }
      });

      growth[collectionName] = {
        total: totalCount,
        period_additions: periodCount,
        growth_rate: totalCount > 0 ? ((periodCount / totalCount) * 100).toFixed(2) : 0
      };
    }

    return growth;
  }

  // Tenant validation and security
  async validateTenantAccess(tenantId) {
    if (!this.tenantRegistry.has(tenantId)) {
      const tenantRegistry = this.db.collection('tenant_registry');
      const tenant = await tenantRegistry.findOne({ tenant_id: tenantId });

      if (!tenant) {
        throw new Error(`Tenant not found: ${tenantId}`);
      }

      if (tenant.status !== 'active') {
        throw new Error(`Tenant inactive: ${tenantId}, status: ${tenant.status}`);
      }

      this.tenantRegistry.set(tenantId, tenant);
    }

    return true;
  }

  async validateTenantDocument(tenantId, collectionName, document) {
    // Apply tenant-specific validation rules
    const tenantConfig = await this.getTenantConfiguration(tenantId);

    // Validate against tenant-specific schema rules
    if (tenantConfig.schema_validation && tenantConfig.schema_validation[collectionName]) {
      const validationRules = tenantConfig.schema_validation[collectionName];

      for (const [field, rules] of Object.entries(validationRules)) {
        if (rules.required && !document[field]) {
          throw new Error(`Required field missing for tenant ${tenantId}: ${field}`);
        }

        if (rules.type && document[field] && typeof document[field] !== rules.type) {
          throw new Error(`Invalid field type for tenant ${tenantId}: ${field}, expected ${rules.type}`);
        }
      }
    }

    return true;
  }

  async getTenantConfiguration(tenantId) {
    if (!this.tenantRegistry.has(tenantId)) {
      await this.validateTenantAccess(tenantId);
    }

    return this.tenantRegistry.get(tenantId).configuration;
  }

  async updateTenantMetrics(tenantId, metricType, metricData) {
    try {
      const performanceMetrics = this.db.collection('tenant_performance_metrics');

      const metric = {
        tenant_id: tenantId,
        metric_type: metricType,
        metric_data: metricData,
        timestamp: new Date()
      };

      await performanceMetrics.insertOne(metric);

      // Update in-memory metrics
      if (this.tenantMetrics.has(tenantId)) {
        const tenantMetric = this.tenantMetrics.get(tenantId);
        tenantMetric.last_activity = new Date();

        if (metricType === 'document_inserted') {
          tenantMetric.total_documents++;
        }
      }

    } catch (error) {
      console.error(`Error updating tenant metrics for ${tenantId}:`, error);
      // Don't throw - metrics shouldn't break operations
    }
  }

  async logTenantActivity(tenantId, action, details) {
    try {
      const auditLog = this.db.collection('tenant_audit_log');

      const logEntry = {
        tenant_id: tenantId,
        action: action,
        details: details,
        timestamp: new Date(),
        user_id: details.user_id || 'system',
        session_id: details.session_id || null
      };

      await auditLog.insertOne(logEntry);

    } catch (error) {
      console.error(`Error logging tenant activity for ${tenantId}:`, error);
      // Don't throw - audit logging shouldn't break operations
    }
  }
}

// Example usage: Multi-tenant SaaS platform implementation
async function demonstrateMultiTenantArchitecture() {
  const multiTenantManager = new MongoDBMultiTenantManager('mongodb://localhost:27017', {
    tenantStrategy: 'shared_database_shared_collection',
    tenantIsolationLevel: 'logical',
    enableTenantSharding: false,
    enableAuditLogging: true,
    enableTenantMetrics: true
  });

  // Register new tenants
  const tenant1 = await multiTenantManager.registerNewTenant({
    tenant_id: 'acme_corp',
    tenant_name: 'Acme Corporation',
    subdomain: 'acme',
    admin_email: '[email protected]',
    subscription_plan: 'enterprise',
    max_users: 100,
    max_storage_gb: 50,
    enable_advanced_analytics: true
  });

  const tenant2 = await multiTenantManager.registerNewTenant({
    tenant_id: 'startup_inc',
    tenant_name: 'Startup Inc',
    subdomain: 'startup',
    admin_email: '[email protected]',
    subscription_plan: 'basic',
    max_users: 10,
    max_storage_gb: 5
  });

  // Create tenant-specific data
  await multiTenantManager.insertTenantDocument('acme_corp', 'customers', {
    company_name: 'Big Client Company',
    contact_email: '[email protected]',
    subscription_status: 'active',
    annual_value: 50000
  });

  await multiTenantManager.insertTenantDocument('startup_inc', 'customers', {
    company_name: 'Small Client LLC',
    contact_email: '[email protected]',
    subscription_status: 'trial',
    annual_value: 5000
  });

  // Query tenant-specific data
  const acmeCustomers = await multiTenantManager.queryTenantDocuments('acme_corp', 'customers');
  const startupCustomers = await multiTenantManager.queryTenantDocuments('startup_inc', 'customers');

  console.log('Acme Corp customers:', acmeCustomers.length);
  console.log('Startup Inc customers:', startupCustomers.length);

  // Generate tenant analytics
  const acmeAnalytics = await multiTenantManager.generateTenantAnalytics('acme_corp', '30d');
  console.log('Acme Corp analytics:', acmeAnalytics);
}

module.exports = {
  MongoDBMultiTenantManager
};

// Enterprise-grade multi-tenant architecture with advanced patterns
class EnterpriseMultiTenantArchitecture extends MongoDBMultiTenantManager {
  constructor(connectionString, enterpriseConfig) {
    super(connectionString, enterpriseConfig);

    this.enterpriseConfig = {
      ...enterpriseConfig,

      // Advanced tenant strategies
      enableTenantSharding: true,
      enableGlobalSecondaryIndexes: true,
      enableCrossRegionReplication: true,
      enableTenantDataEncryption: true,

      // Performance optimization
      enableQueryRouting: true,
      enableConnectionPooling: true,
      enableCaching: true,
      enableReadReplicas: true,

      // Compliance and governance
      enableDataLineage: true,
      enablePIIDetection: true,
      enableGDPRCompliance: true,
      enableSOCCompliance: true
    };
  }

  async implementShardedMultiTenancy(tenants) {
    console.log('Implementing sharded multi-tenancy architecture...');

    // Configure shard key strategy based on tenant distribution
    const shardKeyStrategy = await this.analyzeTenantDistribution(tenants);

    for (const collectionName of ['customers', 'orders', 'products']) {
      await this.enableSharding(collectionName, { tenant_id: 1 });
    }

    // Implement tenant-aware query routing
    await this.setupTenantQueryRouting();

    return shardKeyStrategy;
  }

  async setupTenantSpecificCollections(tenantId) {
    console.log(`Setting up tenant-specific collections for ${tenantId}...`);

    const tenantCollections = ['custom_fields', 'tenant_reports', 'integration_data'];

    for (const collectionName of tenantCollections) {
      const tenantSpecificCollection = `${tenantId}_${collectionName}`;
      const collection = this.db.collection(tenantSpecificCollection);

      // Create tenant-specific indexes and configuration
      await collection.createIndex({ created_at: -1 });
      await collection.createIndex({ updated_at: -1 });

      // Apply tenant-specific data retention policies
      if (collectionName === 'integration_data') {
        await collection.createIndex(
          { created_at: 1 }, 
          { expireAfterSeconds: 30 * 24 * 60 * 60 } // 30 days
        );
      }
    }
  }

  async implementHybridTenantStrategy(tenants) {
    console.log('Implementing hybrid tenant strategy...');

    // Group tenants by size and requirements
    const tenantGroups = this.categorizeTenants(tenants);

    // Large tenants get dedicated collections
    for (const largeTenant of tenantGroups.large) {
      await this.setupTenantSpecificCollections(largeTenant.tenant_id);
    }

    // Medium tenants share collections with optimized indexes
    await this.optimizeSharedCollectionsForMediumTenants(tenantGroups.medium);

    // Small tenants use fully shared collections
    await this.setupSharedCollectionsForSmallTenants(tenantGroups.small);

    return tenantGroups;
  }

  async setupCrossRegionReplication(tenants) {
    console.log('Setting up cross-region replication for tenant data...');

    const replicationStrategies = new Map();

    for (const tenant of tenants) {
      const tenantConfig = await this.getTenantConfiguration(tenant.tenant_id);

      if (tenantConfig.technical_config.enable_replication) {
        const strategy = {
          primary_region: tenantConfig.technical_config.primary_region || 'us-east-1',
          replica_regions: tenantConfig.technical_config.replica_regions || ['us-west-2'],
          read_preference: tenantConfig.technical_config.read_preference || 'primaryPreferred'
        };

        replicationStrategies.set(tenant.tenant_id, strategy);

        // Configure tenant-specific read preferences
        await this.configureTenantReadPreferences(tenant.tenant_id, strategy);
      }
    }

    return replicationStrategies;
  }

  async implementDataResidencyCompliance(tenants) {
    console.log('Implementing data residency and compliance controls...');

    const complianceStrategies = new Map();

    for (const tenant of tenants) {
      const tenantConfig = await this.getTenantConfiguration(tenant.tenant_id);
      const dataResidencyRequirements = tenantConfig.compliance?.data_residency;

      if (dataResidencyRequirements) {
        const strategy = {
          allowed_regions: dataResidencyRequirements.allowed_regions,
          prohibited_regions: dataResidencyRequirements.prohibited_regions,
          encryption_requirements: dataResidencyRequirements.encryption_requirements,
          audit_requirements: dataResidencyRequirements.audit_requirements
        };

        complianceStrategies.set(tenant.tenant_id, strategy);

        // Implement tenant-specific data encryption
        if (strategy.encryption_requirements) {
          await this.setupTenantDataEncryption(tenant.tenant_id, strategy);
        }

        // Setup compliance audit trails
        if (strategy.audit_requirements) {
          await this.setupComplianceAuditing(tenant.tenant_id, strategy);
        }
      }
    }

    return complianceStrategies;
  }
}