smoothschedule/smoothschedule/CLAUDE.md

# SmoothSchedule Backend Development Guide

## Docker-Based Development

**IMPORTANT:** This project runs in Docker containers. Do NOT try to run Django commands directly on the host machine - they will fail due to missing environment variables and database connection.

### Running Django Commands

Always use Docker Compose to execute commands:

```bash
# Navigate to the smoothschedule directory first
cd /home/poduck/Desktop/smoothschedule2/smoothschedule

# Run migrations
docker compose -f docker-compose.local.yml exec django python manage.py migrate

# Run migrations for a specific app
docker compose -f docker-compose.local.yml exec django python manage.py migrate schedule

# Make migrations
docker compose -f docker-compose.local.yml exec django python manage.py makemigrations

# Create superuser
docker compose -f docker-compose.local.yml exec django python manage.py createsuperuser

# Run management commands
docker compose -f docker-compose.local.yml exec django python manage.py <command>

# Access Django shell
docker compose -f docker-compose.local.yml exec django python manage.py shell

# Run tests
docker compose -f docker-compose.local.yml exec django pytest
```

### Multi-Tenant Migrations

This is a multi-tenant app using django-tenants. To run migrations on a specific tenant schema:

```bash
# Run on a specific tenant (e.g., 'demo')
docker compose -f docker-compose.local.yml exec django python manage.py tenant_command migrate --schema=demo

# Run on public schema
docker compose -f docker-compose.local.yml exec django python manage.py migrate_schemas --shared
```

### Docker Services

```bash
# Start all services
docker compose -f docker-compose.local.yml up -d

# View logs
docker compose -f docker-compose.local.yml logs -f django

# Restart Django after code changes (usually auto-reloads)
docker compose -f docker-compose.local.yml restart django

# Rebuild after dependency changes
docker compose -f docker-compose.local.yml up -d --build
```

## Project Structure

### Critical Configuration Files

```
smoothschedule/
├── docker-compose.local.yml          # Local development Docker config
├── docker-compose.production.yml     # Production Docker config
├── .envs/
│   ├── .local/
│   │   ├── .django                   # Django env vars (SECRET_KEY, DEBUG, etc.)
│   │   └── .postgres                 # Database credentials
│   └── .production/
│       ├── .django
│       └── .postgres
├── config/
│   ├── settings/
│   │   ├── base.py                   # Base settings (shared)
│   │   ├── local.py                  # Local dev settings (imports multitenancy.py)
│   │   ├── production.py             # Production settings
│   │   ├── multitenancy.py           # Multi-tenant configuration
│   │   └── test.py                   # Test settings
│   └── urls.py                       # Main URL configuration
├── compose/
│   ├── local/django/
│   │   ├── Dockerfile                # Local Django container
│   │   └── start                     # Startup script
│   └── production/
│       ├── django/
│       ├── postgres/
│       └── traefik/
```

### Django Apps

```
smoothschedule/smoothschedule/
├── users/                            # User management, authentication
│   ├── models.py                     # User model with roles
│   ├── api_views.py                  # Auth endpoints, user API
│   └── migrations/
├── schedule/                         # Core scheduling functionality
│   ├── models.py                     # Resource, Event, Service, Participant
│   ├── serializers.py                # DRF serializers
│   ├── views.py                      # ViewSets for API
│   ├── services.py                   # AvailabilityService
│   └── migrations/
├── tenants/                          # Multi-tenancy (Business/Tenant models)
│   ├── models.py                     # Tenant, Domain models
│   └── migrations/
```

### API Endpoints

Base URL: `http://lvh.me:8000/api/`

- `/api/resources/` - Resource CRUD
- `/api/events/` - Event/Appointment CRUD
- `/api/services/` - Service CRUD
- `/api/customers/` - Customer listing
- `/api/auth/login/` - Authentication
- `/api/auth/logout/` - Logout
- `/api/users/me/` - Current user info
- `/api/business/` - Business settings

## Local Development URLs

- **Backend API:** `http://lvh.me:8000`
- **Frontend:** `http://demo.lvh.me:5173` (business subdomain)
- **Platform Frontend:** `http://platform.lvh.me:5173`

Note: `lvh.me` resolves to `127.0.0.1` and allows subdomain-based multi-tenancy with cookies.

## Database

- **Type:** PostgreSQL with django-tenants
- **Public Schema:** Shared tables (tenants, domains, platform users)
- **Tenant Schemas:** Per-business data (resources, events, customers)

## Common Issues

### 500 Error with No CORS Headers
When Django crashes (500 error), CORS headers aren't sent. Check Django logs:
```bash
docker compose -f docker-compose.local.yml logs django --tail=100
```

### Missing Column/Table Errors
Run migrations:
```bash
docker compose -f docker-compose.local.yml exec django python manage.py migrate
```

### ModuleNotFoundError / ImportError
You're trying to run Python directly instead of through Docker. Use `docker compose exec`.

## Key Models

### Resource (schedule/models.py)
- `name`, `type` (STAFF/ROOM/EQUIPMENT)
- `max_concurrent_events` - concurrency limit (1=exclusive, >1=multilane, 0=unlimited)
- `saved_lane_count` - remembers lane count when multilane disabled
- `buffer_duration` - time between events

### Event (schedule/models.py)
- `title`, `start_time`, `end_time`, `status`
- Links to resources/customers via `Participant` model

### User (users/models.py)
- Roles: `superuser`, `platform_manager`, `platform_support`, `owner`, `manager`, `staff`, `resource`, `customer`
- `business_subdomain` - which tenant they belong to