Users Module Specification

1. Purpose & Overview

The

users

module provides custom user identity management, password hashing, 4-tier Role-Based Access Control (RBAC), and authentication backend management for MetaPilot.

2. Responsibilities

Manage custom
```
User
```
database entity extending Django's
```
AbstractBaseUser
```
and
```
PermissionsMixin
```
.

Maintain

UserRole

enumeration (

SUPER_ADMIN

AGENCY_ADMIN

TENANT_ADMIN

TENANT_USER

Manage superuser creation via
```
UserManager.create_superuser
```
and CLI scripts.

3. Directory Structure

text

services/api/users/
├── admin.py
├── apps.py
├── management/
│   └── commands/
│       └── create_superadmin.py
├── migrations/
├── models.py
├── serializers.py
└── views.py

4. Models & Database Schemas

python

class UserRole(models.TextChoices):
    SUPER_ADMIN = 'SUPER_ADMIN', 'Super Admin'
    AGENCY_ADMIN = 'AGENCY_ADMIN', 'Agency Admin'
    TENANT_ADMIN = 'TENANT_ADMIN', 'Tenant Admin'
    TENANT_USER = 'TENANT_USER', 'Tenant User'

class User(AbstractBaseUser, PermissionsMixin):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    email = models.EmailField(unique=True, db_index=True)
    role = models.CharField(max_length=20, choices=UserRole.choices, default=UserRole.TENANT_USER)
    tenant = models.ForeignKey('tenants.Tenant', on_delete=models.SET_NULL, null=True, blank=True)
    agency = models.ForeignKey('tenants.Agency', on_delete=models.SET_NULL, null=True, blank=True)
    first_name = models.CharField(max_length=150, blank=True)
    last_name = models.CharField(max_length=150, blank=True)
    is_active = models.BooleanField(default=True)
    is_staff = models.BooleanField(default=False)

5. Services & Business Logic

```
UserManager.create_user()
```
: Normalizes email and hashes password with PBKDF2.

UserManager.create_superuser()

: Sets

is_staff=True

is_superuser=True

, and

role=UserRole.SUPER_ADMIN

6. Serializers & Data Transfer Objects

```
UserSerializer
```
: Handles user serialization and validation for User management endpoints.
```
UserCreateSerializer
```
: Validates email uniqueness, password requirements (min 8 chars), and role assignment.

7. Views & API Endpoints

```
GET /api/users/
```
: List users scoped by tenant or agency.
```
POST /api/users/
```
: Create user.
```
GET /api/users/{id}/
```
: Retrieve user profile.
```
DELETE /api/users/{id}/
```
: Delete user access.

8. Permissions & Role Rules

```
SUPER_ADMIN
```
: Can manage users across all agencies and tenants.
```
AGENCY_ADMIN
```
: Can manage users within clients under their agency.
```
TENANT_ADMIN
```
: Can manage users within their own tenant organization.

9. Signals & Event Listeners

```
post_save
```
: Automatically triggers audit log entries upon user role modification.

10. Background Tasks & Celery Jobs

None (User authentication operates synchronously).

11. Data Flow & External Dependencies

Integrates with
```
rest_framework_simplejwt
```
for issuing signed JWT access and refresh tokens.

12. Business Rules & Validations

Email addresses must be unique across the platform.
Password length must be at least 8 characters.

13. Sequence Diagram (Mermaid)

Rendering diagram...

14. Known Limitations & Technical Debt

Single primary tenant relationship per user (users cannot switch active tenants without re-authentication).

15. Future Improvements

Add Multi-Factor Authentication (MFA / 2FA) support using TOTP applications.

Users & Auth Module