telegram-management-system/marketing-agent/MULTI_TENANT.md

Multi-Tenant Architecture

This document describes the multi-tenant implementation for the Telegram Marketing Intelligence Agent System.

Overview

The system supports full multi-tenant isolation, allowing multiple organizations to use the same instance while keeping their data completely separated.

Architecture

Tenant Model

Each tenant has:

• Basic Information: Name, slug, domain
• Plan & Limits: Subscription plan with resource limits
• Usage Tracking: Real-time usage monitoring
• Billing: Integrated billing and payment tracking
• Settings: Customizable preferences per tenant
• Branding: White-label support for enterprise plans
• Features: Plan-based feature toggles
• Compliance: GDPR and data retention settings

Data Isolation

All data models include a tenantId field that ensures complete data isolation:

• MongoDB models use compound indexes with tenantId
• Sequelize models use foreign key references
• All queries automatically filter by current tenant

Tenant Context

The tenant context is determined through multiple methods:

1. Subdomain: acme.app.com → tenant: acme
2. Custom Domain: app.acme.com → tenant: acme
3. Header: X-Tenant-Id for API access
4. URL Parameter: ?tenant=acme for multi-tenant admin
5. User Association: From authenticated user's tenant

Implementation

1. Tenant Middleware

// Automatically adds tenant context to all requests
app.use(tenantMiddleware);
app.use(allowCrossTenant); // For superadmin access

2. Model Updates

All models now include tenantId:

const schema = new Schema({
  tenantId: {
    type: ObjectId,
    ref: 'Tenant',
    required: true,
    index: true
  },
  // ... other fields
});

3. API Routes

Public Routes

• POST /api/v1/tenants/signup - Create new tenant

Tenant Routes (Authenticated)

• GET /api/v1/tenants/current - Get current tenant
• PATCH /api/v1/tenants/current/settings - Update settings
• PATCH /api/v1/tenants/current/branding - Update branding
• GET /api/v1/tenants/current/usage - Get usage statistics

Superadmin Routes

• GET /api/v1/tenants - List all tenants
• PATCH /api/v1/tenants/:id - Update any tenant
• DELETE /api/v1/tenants/:id - Delete tenant

4. Frontend Components

Tenant Settings

• Location: /dashboard/tenant/settings
• Features:
  • General settings (timezone, language, currency)
  • Security settings (2FA, SSO)
  • Branding (logo, colors, custom CSS)
  • Usage monitoring and limits
  • Compliance configuration

Tenant Management (Superadmin)

• Location: /dashboard/tenants
• Features:
  • List all tenants with filtering
  • Edit tenant plans and limits
  • Suspend/activate tenants
  • Login as tenant
  • Delete tenants

Plans & Features

Free Plan

• 5 users
• 10 campaigns
• 1,000 messages/month
• Basic analytics
• Community support

Starter Plan ($29/month)

• 20 users
• 50 campaigns
• 10,000 messages/month
• Automation
• API access
• Email support

Professional Plan ($99/month)

• 100 users
• 200 campaigns
• 50,000 messages/month
• A/B testing
• Custom reports
• Multi-language
• Priority support

Enterprise Plan (Custom)

• Unlimited everything
• White-label branding
• AI suggestions
• SLA guarantee
• Dedicated support

Resource Limits

Each tenant has configurable limits:

• users: Maximum number of users
• campaigns: Maximum number of campaigns
• messagesPerMonth: Monthly message limit
• telegramAccounts: Number of Telegram accounts
• storage: Storage quota in bytes
• apiCallsPerHour: API rate limiting
• webhooks: Number of webhooks
• customIntegrations: Enable/disable custom integrations

Usage Tracking

The system tracks usage in real-time:

// Check limit before operation
if (!tenant.checkLimit('campaigns')) {
  throw new Error('Campaign limit exceeded');
}

// Increment usage after successful operation
await tenant.incrementUsage('campaigns');

// Monthly reset for message limits
await tenant.resetMonthlyUsage();

Security Considerations

Tenant Isolation

• All database queries include tenant filtering
• Compound indexes ensure query performance
• Cross-tenant access blocked except for superadmin

Authentication

• Users belong to a single tenant
• Tenant context included in JWT tokens
• API keys scoped to tenant

Compliance

• Per-tenant GDPR settings
• Configurable data retention
• IP whitelisting support
• Audit logging per tenant

Migration Guide

For Existing Installations

1. Backup your data before migration

2. Run migration script:

   node scripts/migrate-to-multitenant.js
   

3. Update environment variables:

   DEFAULT_TENANT_SLUG=default
   ENABLE_MULTI_TENANT=true
   

4. Test tenant isolation:

   npm run test:multitenant
   

For New Installations

Multi-tenancy is enabled by default. The first user signup creates a new tenant automatically.

Best Practices

Development

1. Always include tenantId in queries
2. Use tenant middleware for automatic filtering
3. Test with multiple tenants in development
4. Validate tenant limits before operations

Production

1. Monitor tenant usage regularly
2. Set up alerts for limit approaching
3. Implement proper backup strategies per tenant
4. Use custom domains for enterprise tenants

Performance

1. Ensure all queries use tenant indexes
2. Monitor slow queries per tenant
3. Implement caching strategies
4. Use read replicas for analytics

Troubleshooting

Common Issues

1. "Tenant not found" error

   • Check tenant slug/domain configuration
   • Verify tenant status is active
   • Check subdomain DNS settings

2. Data visible across tenants

   • Ensure tenantId is in all queries
   • Check model indexes
   • Verify middleware is applied

3. Performance degradation

   • Check compound index usage
   • Monitor per-tenant query patterns
   • Consider sharding large tenants

Debug Mode

Enable tenant debug logging:

// In development
process.env.TENANT_DEBUG = 'true';

This logs all tenant resolution and filtering operations.

Future Enhancements

1. Tenant Sharding: Distribute large tenants across databases
2. Tenant Templates: Pre-configured tenant setups
3. Tenant Marketplace: Share templates/workflows between tenants
4. Advanced Analytics: Cross-tenant analytics for superadmin
5. Automated Scaling: Dynamic resource allocation based on usage