237c7802e5
Some checks failed
Deploy / deploy (push) Has been cancelled
Full-stack web application for Telegram management - Frontend: Vue 3 + Vben Admin - Backend: NestJS - Features: User management, group broadcast, statistics 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
260 lines
6.4 KiB
Markdown
260 lines
6.4 KiB
Markdown
# 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
|
|
|
|
```javascript
|
|
// Automatically adds tenant context to all requests
|
|
app.use(tenantMiddleware);
|
|
app.use(allowCrossTenant); // For superadmin access
|
|
```
|
|
|
|
### 2. Model Updates
|
|
|
|
All models now include tenantId:
|
|
```javascript
|
|
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:
|
|
```javascript
|
|
// 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**:
|
|
```bash
|
|
node scripts/migrate-to-multitenant.js
|
|
```
|
|
|
|
3. **Update environment variables**:
|
|
```env
|
|
DEFAULT_TENANT_SLUG=default
|
|
ENABLE_MULTI_TENANT=true
|
|
```
|
|
|
|
4. **Test tenant isolation**:
|
|
```bash
|
|
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:
|
|
```javascript
|
|
// 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 |