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:

```bash
# 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:

```bash
# 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:

```python
# 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:

```python
# 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:
```bash
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!