Tenants Module Specification

1. Purpose & Overview

The

tenants

module manages account tenancy, agency organization structures, encrypted credential storage (

TenantConfig

), tenant middleware resolution, and platform audit logging.

2. Responsibilities

Maintain
```
Tenant
```
,
```
Agency
```
,
```
TenantConfig
```
, and
```
AuditLog
```
domain models.
Enforce tenant request resolution via
```
TenantMiddleware
```
.
Perform Fernet AES-256 symmetric encryption/decryption for Meta WhatsApp access tokens.

3. Directory Structure

text

services/api/tenants/
├── admin.py
├── apps.py
├── middleware.py
├── migrations/
├── models.py
├── serializers.py
└── views.py

4. Models & Database Schemas

python

class Agency(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    name = models.CharField(max_length=255)
    slug = models.SlugField(unique=True)

class Tenant(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    agency = models.ForeignKey(Agency, on_delete=models.CASCADE, related_name='tenants')
    name = models.CharField(max_length=255)
    slug = models.SlugField(unique=True)

class TenantConfig(models.Model):
    tenant = models.ForeignKey(Tenant, on_delete=models.CASCADE)
    provider = models.CharField(max_length=50) # 'meta'
    key_name = models.CharField(max_length=100) # 'wa_access_token'
    encrypted_value = models.TextField()

class AuditLog(models.Model):
    tenant = models.ForeignKey(Tenant, on_delete=models.SET_NULL, null=True)
    user = models.ForeignKey('users.User', on_delete=models.SET_NULL, null=True)
    action = models.CharField(max_length=100)
    resource = models.CharField(max_length=100)
    details = models.JSONField(default=dict)
    created_at = models.DateTimeField(auto_now_add=True)

5. Services & Business Logic

TenantConfig.set_value(plain_value)

: Encrypts string using

Fernet(settings.FERNET_KEY)

```
TenantConfig.get_value()
```
: Decrypts
```
encrypted_value
```
back to plain string.
```
TenantConfig.get_fernet()
```
: Initializes Fernet instance with development fallback support.

6. Serializers & Data Transfer Objects

```
TenantSerializer
```
: Handles client creation and automatically encrypts
```
wa_access_token
```
.
```
AuditLogSerializer
```
: Serializes system audit records for Super Admin inspection.

7. Views & API Endpoints

```
GET /api/clients/
```
: List tenants.
```
POST /api/clients/
```
: Create tenant (encrypts access token).
```
GET /api/clients/{id}/configs/
```
: View tenant configurations.
```
GET /api/audit-logs/
```
: View system audit logs.

8. Permissions & Role Rules

```
SUPER_ADMIN
```
: Can view and create all tenants and audit logs.
```
AGENCY_ADMIN
```
: Can view clients linked to their agency.

9. Signals & Event Listeners

```
post_save
```
on
```
Tenant
```
&
```
User
```
: Automatically generates
```
AuditLog
```
records.

10. Background Tasks & Celery Jobs

None (Tenant configuration operations are synchronous).

11. Data Flow & External Dependencies

Uses Python
```
cryptography.fernet.Fernet
```
library for AES-256 secret encryption.

12. Business Rules & Validations

```
FERNET_KEY
```
must be a valid 32 url-safe base64-encoded string.

DEBUG=True

mode, fallback key

KHS39TFFYZFLCfUNv1NNbPRZN2C1w7FKYmsl4ZcJ-Ok=

is used if unconfigured.

13. Sequence Diagram (Mermaid)

Rendering diagram...

14. Known Limitations & Technical Debt

Single primary Fernet key used for all tenants.

15. Future Improvements

Support envelope encryption with per-tenant encryption keys stored in AWS KMS / Vault.