smoothschedule/smoothschedule/SANDBOX_MODE_IMPLEMENTATION.md

Sandbox Mode Implementation Summary

Overview

Sandbox/Test mode provides complete data isolation for testing. Users can toggle between Live and Test modes via a switch in the header. Each mode has its own:

• Database schema (for tenant-specific data like appointments, resources, services)
• Customer records (filtered by is_sandbox flag on User model)

Architecture

Backend Components

1. Tenant Model (core/models.py)

   • sandbox_schema_name: PostgreSQL schema for sandbox data (e.g., demo_sandbox)
   • sandbox_enabled: Boolean to enable/disable sandbox for tenant
   • Auto-generates sandbox schema name on save

2. SandboxModeMiddleware (core/middleware.py:16-118)

   • Switches database schema based on:
     • API token prefix (ss_test_* = sandbox, ss_live_* = live)
     • X-Sandbox-Mode: true header
     • Session value sandbox_mode
   • Sets request.sandbox_mode = True/False for views to use
   • MUST run AFTER SessionMiddleware in middleware order

3. User Model (smoothschedule/users/models.py)

   • is_sandbox: Boolean field to mark sandbox customers
   • Live customers have is_sandbox=False, test customers have is_sandbox=True

4. API Endpoints (schedule/api_views.py)

   • GET /api/sandbox/status/ - Get current sandbox state
   • POST /api/sandbox/toggle/ - Toggle sandbox mode (sets session)

5. CustomerViewSet (schedule/views.py:199-249)

   • Filters customers by request.sandbox_mode
   • perform_create sets is_sandbox based on current mode

6. StaffViewSet (schedule/views.py:302-366)

   • Filters staff by request.sandbox_mode
   • Staff created via invitations inherit sandbox mode from request

7. TicketViewSet (tickets/views.py:65-167)

   • Filters tickets by request.sandbox_mode (except PLATFORM tickets)
   • perform_create sets is_sandbox based on current mode
   • PLATFORM tickets are always created in live mode

8. PublicCustomerViewSet (public_api/views.py:888-968)

   • Also filters by sandbox mode for API customers

9. APIToken Model (public_api/models.py)

   • is_sandbox: Boolean for token type
   • Key prefixes: ss_test_* (sandbox) or ss_live_* (live)

Frontend Components

1. SandboxContext (contexts/SandboxContext.tsx)

   • Provides isSandbox, sandboxEnabled, toggleSandbox, isToggling
   • Syncs state to localStorage for API client

2. SandboxToggle (components/SandboxToggle.tsx)

   • Toggle switch component with Live/Test labels

3. SandboxBanner (components/SandboxBanner.tsx)

   • Orange warning banner shown in test mode

4. API Client (api/client.ts:23-51)

   • Reads localStorage.getItem('sandbox_mode')
   • Adds X-Sandbox-Mode: true header when in sandbox

5. BusinessLayout (layouts/BusinessLayout.tsx)

   • Wrapped with SandboxProvider
   • Shows SandboxBanner when in test mode

6. TopBar (components/TopBar.tsx)

   • Includes SandboxToggle component

Configuration

1. CORS (config/settings/local.py:75-78)

   • x-sandbox-mode added to CORS_ALLOW_HEADERS

2. Middleware Order (config/settings/multitenancy.py:89-122)

   • SandboxModeMiddleware MUST come AFTER SessionMiddleware

Database Schemas

Each tenant has two schemas:

• {tenant_name} - Live data (e.g., demo)
• {tenant_name}_sandbox - Test data (e.g., demo_sandbox)

Schemas created via: python manage.py create_sandbox_schemas

What's Isolated

Data Type	Isolation Method
Appointments/Events	Schema switching (automatic)
Resources	Schema switching (automatic)
Services	Schema switching (automatic)
Payments	Schema switching (automatic)
Notifications	Schema switching (automatic)
Communication	Schema switching (automatic)
Customers	is_sandbox field on User model
Staff Members	is_sandbox field on User model
Tickets (CUSTOMER/STAFF_REQUEST/INTERNAL)	is_sandbox field on Ticket model
Tickets (PLATFORM)	NOT isolated (always live - platform support)
Business Settings (Tenant)	NOT isolated (shared between modes)

Key Files Modified

Backend

• core/models.py - Tenant sandbox fields
• core/middleware.py - SandboxModeMiddleware
• smoothschedule/users/models.py - User.is_sandbox field
• smoothschedule/users/api_views.py - accept_invitation_view sets is_sandbox
• schedule/views.py - CustomerViewSet and StaffViewSet sandbox filtering
• schedule/api_views.py - sandbox_status_view, sandbox_toggle_view
• tickets/models.py - Ticket.is_sandbox field
• tickets/views.py - TicketViewSet sandbox filtering
• public_api/models.py - APIToken.is_sandbox
• public_api/views.py - PublicCustomerViewSet sandbox filtering
• config/settings/local.py - CORS headers
• config/settings/multitenancy.py - Middleware order, tickets in SHARED_APPS

Frontend

• src/api/sandbox.ts - API functions
• src/api/client.ts - X-Sandbox-Mode header
• src/hooks/useSandbox.ts - React Query hooks
• src/contexts/SandboxContext.tsx - Context provider
• src/components/SandboxToggle.tsx - Toggle UI
• src/components/SandboxBanner.tsx - Warning banner
• src/components/TopBar.tsx - Added toggle
• src/layouts/BusinessLayout.tsx - Provider + banner
• src/i18n/locales/en.json - Translations

Migrations

# Migrations for User.is_sandbox and Ticket.is_sandbox fields
cd /home/poduck/Desktop/smoothschedule2/smoothschedule
docker compose -f docker-compose.local.yml exec django python manage.py migrate

Current State

• ✅ Sandbox mode toggle works
• ✅ CORS configured for X-Sandbox-Mode header
• ✅ Customer isolation by is_sandbox field implemented
• ✅ Staff isolation by is_sandbox field implemented
• ✅ Ticket isolation by is_sandbox field implemented (except PLATFORM tickets)
• ✅ Appointments/Events/Resources/Services automatically isolated via schema switching
• ✅ Existing users are is_sandbox=False (live)
• ✅ Existing tickets are is_sandbox=False (live)
• ✅ Test mode shows empty data (clean sandbox)