smoothschedule/PLATFORM_INTEGRATION.md

Platform Integration Summary

What We've Completed

✅ Backend (Django)

1. Created Platform App (smoothschedule/platform/)

   • apps.py - App configuration
   • serializers.py - TenantSerializer, PlatformUserSerializer, PlatformMetricsSerializer
   • permissions.py - IsPlatformAdmin, IsPlatformUser
   • views.py - TenantViewSet, PlatformUserViewSet
   • urls.py - URL routing

2. API Endpoints Created

   • GET /api/platform/businesses/ - List all tenants
   • GET /api/platform/businesses/{id}/ - Get specific tenant
   • GET /api/platform/businesses/metrics/ - Get platform metrics
   • GET /api/platform/users/ - List all users
   • GET /api/platform/users/{id}/ - Get specific user

3. Configuration Updates

   • Added platform to INSTALLED_APPS in config/settings/base.py
   • Added platform URLs to config/urls.py

✅ Frontend (React)

The frontend already has complete implementation from the tarball:

1. Platform Pages

   • pages/platform/PlatformDashboard.tsx - Metrics and charts
   • pages/platform/PlatformBusinesses.tsx - Tenant list with masquerade
   • pages/platform/PlatformUsers.tsx - User management
   • pages/platform/PlatformSupport.tsx - Support tickets
   • pages/platform/PlatformSettings.tsx - Platform settings

2. Routing

   • Role-based access configured in App.tsx
   • Routes protected by user role (SUPERUSER, PLATFORM_MANAGER, etc.)

3. API Integration

   • hooks/usePlatform.ts - React Query hooks
   • api/platform.ts - API client functions

Next Steps

1. Restart Django Server

The Django server needs to be restarted to pick up the new platform app:

# Stop the current server (Ctrl+C in the terminal)
# Then restart it
docker-compose -f docker-compose.local.yml restart django

2. Test API Endpoints

Once the server is restarted, test the endpoints:

# List all tenants (requires authentication)
curl -H "Authorization: Bearer YOUR_TOKEN" http://lvh.me:8000/api/platform/businesses/

# List all users
curl -H "Authorization: Bearer YOUR_TOKEN" http://lvh.me:8000/api/platform/users/

3. Create Platform Admin User

You need a user with platform admin role to access these endpoints:

# In Django shell
from smoothschedule.users.models import User

# Create or update a superuser
user = User.objects.filter(username='admin').first()
if user:
    user.role = User.Role.SUPERUSER
    user.is_staff = True
    user.is_superuser = True
    user.save()

4. Test Frontend

1. Navigate to http://platform.lvh.me:5173/
2. Login with platform admin credentials
3. You should see:
   • Platform Dashboard with metrics
   • Businesses page showing all tenants
   • Users page showing all users
   • Support and Settings pages

Known Limitations

Need to Add Tenant Reference to User Model

Currently, the User model doesn't have a direct reference to which Tenant they belong to. This is needed for:

• Showing business name in user list
• Filtering users by business
• Getting accurate owner information

To fix: Add a foreign key to User model:

# In smoothschedule/users/models.py
from core.models import Tenant

class User(AbstractUser):
    # ... existing fields ...

    tenant = models.ForeignKey(
        Tenant,
        on_delete=models.CASCADE,
        null=True,
        blank=True,
        related_name='users',
        help_text="Tenant this user belongs to (null for platform users)"
    )

Then run migrations:

python manage.py makemigrations
python manage.py migrate

Architecture Notes

Multi-Tenancy with django-tenants

• Public Schema: Stores Tenant and Domain models
• Tenant Schemas: Each tenant gets isolated PostgreSQL schema
• Platform API: Operates on public schema to list all tenants
• User Model: Stored in public schema (shared across tenants)

Permission Model

1. Platform Roles (access all tenants):

   • SUPERUSER - Full access
   • PLATFORM_MANAGER - Manage tenants and users
   • PLATFORM_SUPPORT - View-only access
   • PLATFORM_SALES - Sales operations

2. Tenant Roles (access single tenant):

   • TENANT_OWNER - Tenant administrator
   • TENANT_MANAGER - Manage tenant settings
   • TENANT_STAFF - Use tenant features

3. Customer Role:

   • CUSTOMER - End user of tenant

File Structure

smoothschedule/
├── platform/               # NEW - Platform management app
│   ├── __init__.py
│   ├── apps.py
│   ├── serializers.py     # API serializers
│   ├── permissions.py     # Custom permissions
│   ├── views.py           # ViewSets
│   └── urls.py            # URL routing
├── core/
│   └── models.py          # Tenant, Domain models
├── smoothschedule/users/
│   └── models.py          # User model
└── config/
    ├── settings/base.py   # Updated INSTALLED_APPS
    └── urls.py            # Added platform URLs

Testing the Complete Flow

1. Backend: Platform API serving tenant/user data
2. Frontend: React app consuming API and displaying in UI
3. Authentication: Role-based access control
4. Multi-tenancy: Proper isolation between tenants

Once the server is restarted and a platform admin user is created, the entire platform section should be functional!