QNova Database Models

This directory contains all the Mongoose models for the QNova multi-tenant system. Each model is defined in a separate file with proper TypeScript interfaces and MongoDB indexes.

Models Overview

Core Tenant Models

1. Tenant (tenant.model.ts)

• Primary tenant entity with authentication settings and password policies
• Indexes: { tenantKey: 1 } (unique)
• Key Features:
  • Multi-factor authentication settings
  • Configurable password policies (bcrypt/argon2id)
  • Feature flags system
  • SSO provider management

2. TenantDomain (tenantDomain.model.ts)

• Domain verification and management for tenants
• Indexes:
  • { tenantDomain: 1 } (unique)
  • { tenantId: 1 } (unique)
• Key Features:
  • Subdomain, tenant domain, and email domain verification
  • Three-state verification status (pending/verified/failed)

3. TenantBranding (tenantBranding.model.ts)

• Tenant-specific branding and theming
• Indexes: { tenantId: 1 } (unique)
• Key Features:
  • Primary/secondary colors
  • Custom fonts
  • Logo, icon, and favicon URLs

Organization & User Models

4. Organization (organization.model.ts)

• Organizations within tenants
• Indexes:
  • { tenantId: 1, orgKey: 1 } (unique)
  • { tenantId: 1, name: 1 }
• Key Features:
  • IP blacklisting and whitelisting
  • Per-organization feature overrides
  • Contact information management

5. User (user.model.ts)

• System users with authentication and profile data
• Indexes:
  • { tenantId: 1, email: 1 } (unique, sparse)
  • { tenantId: 1, status: 1 }
• Key Features:
  • Password history and lockout management
  • Multi-factor authentication (TOTP/WebAuthn)
  • OAuth provider integration
  • User status management (active/invited/disabled)

6. UserToken (userToken.model.ts)

• Single-use tokens for invites and password resets
• Indexes:
  • { tokenHash: 1 } (unique)
  • { expiresAt: 1 } (TTL index for auto-pruning)
  • { userId: 1, type: 1, consumedAt: 1 }
• Key Features:
  • Secure token hashing
  • Automatic expiration
  • Usage tracking with IP and user agent

Agent & Skills Models

7. Agent (agent.model.ts)

• External agents with skills and team assignments
• Indexes:
  • { tenantId: 1, fullName: 1 }
  • { tenantId: 1, email: 1 } (unique, sparse)
  • { tenantId: 1, servicePartnerId: 1, isActive: 1 }
• Key Features:
  • Skill assignment (embedded array for performance)
  • Campaign associations
  • Service partner relationships

8. Skill (skill.model.ts)

• Organization-scoped skill catalog
• Indexes:
  • { tenantId: 1, name: 1 } (unique)
  • { tenantId: 1, category: 1 }
• Key Features:
  • Categorization and weighting
  • Tenant-scoped uniqueness

Permission & Role Models

9. Permission (permission.model.ts)

• Immutable permission atoms
• Indexes:
  • { code: 1 } (unique)
  • { domain: 1, action: 1 }
  • { weight: 1 }
• Key Features:
  • Domain.action structure
  • Hierarchical weighting (10=read, 20=write, 30=manage)

10. Role (role.model.ts)

• Roles with permission collections
• Indexes: { tenantId: 1, name: 1 } (unique, sparse)
• Key Features:
  • System vs tenant-specific roles
  • Permission aggregation

11. RoleBinding (roleBinding.model.ts)

• User-role assignments with scope and filters
• Indexes:
  • { tenantId: 1, userId: 1, 'scope.type': 1, 'scope.resourceId': 1 }
  • { tenantId: 1, roleId: 1 }
  • { userId: 1, 'scope.type': 1 }
  • Unique compound index for role binding uniqueness
• Key Features:
  • Multi-level scoping (tenant/organization/project/etc.)
  • Lookup filters for fine-grained access control
  • Assignment tracking

Common Patterns

MetaData Schema

All models (except Permission and UserToken) include a standardized metaData object with:

• createdAt / updatedAt timestamps
• createdBy / updatedBy user references
• Soft deletion with isDeleted / deletedAt
• Legacy ID mapping support

Pre-save Middleware

Most models include middleware to automatically update metaData.updatedAt on document modifications.

Multi-tenancy

All models are designed with tenant isolation in mind, with tenantId fields and appropriate indexes for efficient tenant-scoped queries.

Usage

import { 
  Tenant, 
  User, 
  Organization, 
  RoleBinding,
  // ... other models
} from './models';

// Example: Create a new tenant
const tenant = new Tenant({
  tenantKey: 'acme-corp',
  name: 'Acme Corporation',
  contact: { email: '[email protected]' },
  settings: {
    auth: {
      ssoEnabled: false,
      allowedIdPs: [],
      mfaEnforced: true,
      passwordPolicy: {
        minLength: 12,
        requireUppercase: true,
        // ... other policy settings
      }
    },
    features: new Map([['analytics', true]])
  },
  metaData: {
    createdBy: adminUserId,
    updatedBy: adminUserId
  }
});

await tenant.save();

Database Indexes Summary

All models include carefully designed indexes for:

• Uniqueness constraints (tenant keys, emails, etc.)
• Multi-tenant queries (tenantId-based lookups)
• Performance optimization (frequently queried fields)
• TTL expiration (automatic cleanup for tokens)

The indexes are designed to support the multi-tenant architecture while maintaining query performance across all tenant operations.