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:

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

# 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

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

docker compose -f docker-compose.local.yml logs django --tail=100

Missing Column/Table Errors

Run migrations:

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