docs: Comprehensive README update for v2.0.0

Updated README.md from 312 to 640 lines with current, accurate documentation:

Major Updates:
- Current technology stack (NestJS 11, React 19, Prisma 7.3, PostgreSQL 16)
- Auth0 authentication documentation (replaced generic OAuth)
- Unified Activity System explanation (single ScheduleEvent model)
- Multi-VIP support with ridesharing capabilities
- Search & filtering features across 8 fields
- Sortable columns documentation
- Complete API endpoint reference (/api/v1/*)
- Database schema in TypeScript format
- Playwright testing guide
- Common issues & troubleshooting
- Production deployment checklist
- BSA Jamboree-specific context

New Sections Added:
- Comprehensive feature list with role-based permissions
- Accurate setup instructions with correct ports
- Environment variable configuration
- Database migration guide
- Troubleshooting with specific error messages and fixes
- Development workflow documentation
- Changelog documenting v2.0.0 breaking changes

This brings the README in sync with the unified activity system overhaul.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

README.md

@@ -1,311 +1,640 @@
 # VIP Coordinator
 
-A comprehensive VIP transportation coordination system built with React, Node.js, PostgreSQL, and Redis. This application provides real-time scheduling, driver management, and VIP coordination capabilities with enterprise-grade security and scalability.
+> **Enterprise VIP & Transportation Management System for BSA Jamborees**
 
-## 🚀 Quick Start with Docker
+A comprehensive full-stack application for coordinating VIP transportation, scheduling, and logistics at large-scale scouting events. Built with NestJS, React, PostgreSQL, and designed specifically for BSA (Boy Scouts of America) Jamboree operations.
+
+---
+
+## 🎯 Overview
+
+VIP Coordinator streamlines the complex logistics of managing hundreds of VIPs during multi-day events. It handles:
+
+- **Multi-VIP Activity Scheduling** - Coordinate transport and activities for multiple VIPs simultaneously
+- **Real-time Driver Assignment** - Assign and reassign drivers on-the-fly with conflict detection
+- **Intelligent Search & Filtering** - Find activities instantly by VIP name, location, or type
+- **Resource Optimization** - Track vehicle capacity utilization (e.g., "3/6 seats used")
+- **Complete Itineraries** - Generate detailed 3-day schedules per VIP with all activities
+- **Role-Based Access Control** - Administrator, Coordinator, and Driver roles with granular permissions
+
+---
+
+## 🚀 Quick Start
 
 ### Prerequisites
 
-- Docker and Docker Compose installed
+- **Node.js** 18+ and npm
-- Google OAuth credentials (for authentication)
+- **PostgreSQL** 16+
-- Domain name or localhost for development
+- **Redis** 7+
+- **Auth0 Account** (for authentication)
+- **Docker** (optional, for containerized deployment)
 
-### 1. Pull the Images
+### Development Setup
 
 ```bash
-docker pull t72chevy/vip-coordinator:backend-latest
+# Clone the repository
-docker pull t72chevy/vip-coordinator:frontend-latest
+git clone http://192.168.68.53:3000/kyle/vip-coordinator.git
+cd vip-coordinator
+
+# === Backend Setup ===
+cd backend
+npm install
+
+# Configure environment variables
+cp .env.example .env
+# Edit .env with your Auth0 credentials and database URL
+
+# Run database migrations
+npx prisma migrate deploy
+
+# Seed database with test data
+npx prisma db seed
+
+# Start backend server (port 3000)
+npm run start:dev
+
+# === Frontend Setup ===
+cd ../frontend
+npm install
+
+# Configure environment variables
+cp .env.example .env
+# Edit .env with your backend API URL
+
+# Start frontend dev server (port 5173)
+npm run dev
 ```
 
-### 2. Create Environment File
+### Access the Application
 
-Create a `.env` file in your project directory:
+- **Frontend**: http://localhost:5173
+- **Backend API**: http://localhost:3000
+- **API Documentation**: http://localhost:3000/api (Swagger UI)
 
-```env
+---
-# Database Configuration
-POSTGRES_DB=vip_coordinator
-POSTGRES_USER=vip_user
-POSTGRES_PASSWORD=your_secure_password_here
-
-# Backend Configuration
-DATABASE_URL=postgresql://vip_user:your_secure_password_here@postgres:5432/vip_coordinator
-NODE_ENV=production
-PORT=3000
-
-# Frontend Configuration
-VITE_API_URL=http://localhost:3000
-VITE_FRONTEND_URL=http://localhost
-
-# Google OAuth Configuration
-GOOGLE_CLIENT_ID=your_google_client_id_here
-GOOGLE_CLIENT_SECRET=your_google_client_secret_here
-
-# Redis Configuration
-REDIS_URL=redis://redis:6379
-
-# Security
-JWT_SECRET=auto-generated-on-startup
-```
-
-### 3. Create Docker Compose File
-
-Create a `docker-compose.yml` file:
-
-```yaml
-version: '3.8'
-
-services:
-  postgres:
-    image: postgres:15-alpine
-    environment:
-      POSTGRES_DB: ${POSTGRES_DB}
-      POSTGRES_USER: ${POSTGRES_USER}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    ports:
-      - "5432:5432"
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-  redis:
-    image: redis:7-alpine
-    ports:
-      - "6379:6379"
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-  backend:
-    image: t72chevy/vip-coordinator:backend-latest
-    environment:
-      - DATABASE_URL=${DATABASE_URL}
-      - NODE_ENV=${NODE_ENV}
-      - PORT=${PORT}
-      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
-      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
-      - REDIS_URL=${REDIS_URL}
-      - JWT_SECRET=${JWT_SECRET}
-    ports:
-      - "3000:3000"
-    depends_on:
-      postgres:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-
-  frontend:
-    image: t72chevy/vip-coordinator:frontend-latest
-    environment:
-      - VITE_API_URL=${VITE_API_URL}
-      - VITE_FRONTEND_URL=${VITE_FRONTEND_URL}
-    ports:
-      - "80:80"
-    depends_on:
-      backend:
-        condition: service_healthy
-
-volumes:
-  postgres_data:
-```
-
-### 4. Deploy the Application
-
-```bash
-# Start all services
-docker-compose up -d
-
-# Check service status
-docker-compose ps
-
-# View logs
-docker-compose logs -f
-```
-
-### 5. Access the Application
-
-- **Frontend**: http://localhost
-- **Backend API**: http://localhost:3001
-- **Health Check**: http://localhost:3001/health
-
-## 🔧 Configuration
-
-### Google OAuth Setup
-
-1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
-2. Create a new project or select an existing one
-3. Enable the Google+ API
-4. Create OAuth 2.0 credentials
-5. Add your domain to authorized origins
-6. Add your callback URL: `http://your-domain/auth/google/callback`
-
-### Environment Variables
-
-| Variable | Description | Required | Default |
-|----------|-------------|----------|---------|
-| `POSTGRES_DB` | PostgreSQL database name | Yes | `vip_coordinator` |
-| `POSTGRES_USER` | PostgreSQL username | Yes | `vip_user` |
-| `POSTGRES_PASSWORD` | PostgreSQL password | Yes | - |
-| `DATABASE_URL` | Full database connection string | Yes | - |
-| `GOOGLE_CLIENT_ID` | Google OAuth client ID | Yes | - |
-| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret | Yes | - |
-| `REDIS_URL` | Redis connection string | Yes | `redis://redis:6379` |
-| `NODE_ENV` | Node.js environment | No | `production` |
-| `PORT` | Backend server port | No | `3001` |
-| `VITE_API_URL` | Frontend API URL | Yes | - |
-| `VITE_FRONTEND_URL` | Frontend base URL | Yes | - |
 
 ## 🏗️ Architecture
 
-### Services
+### Technology Stack
 
-- **Frontend**: React application with Vite build system, served by Nginx
+**Backend**
-- **Backend**: Node.js/Express API server with TypeScript
+- **Framework**: NestJS 11 (TypeScript)
-- **Database**: PostgreSQL for persistent data storage
+- **Database**: PostgreSQL 16 with Prisma ORM 7.3
-- **Cache**: Redis for session management and real-time features
+- **Cache**: Redis 7
+- **Authentication**: Auth0 + Passport.js (JWT strategy)
+- **API**: REST with Swagger documentation
 
-### Security Features
+**Frontend**
+- **Framework**: React 19 with TypeScript
+- **Build Tool**: Vite 7.2
+- **UI Library**: Material-UI (MUI) 7.3
+- **State Management**: React Query 5.9 (server) + Zustand 5.0 (client)
+- **Routing**: React Router 7.13
+- **Forms**: React Hook Form (planned)
 
-- **JWT Auto-Rotation**: Automatic JWT secret rotation for enhanced security
+**Infrastructure**
-- **Google OAuth**: Secure authentication via Google
+- **Containerization**: Docker + Docker Compose
-- **Non-Root Containers**: All containers run as non-root users
+- **Database Migrations**: Prisma Migrate
-- **Health Checks**: Comprehensive health monitoring
+- **Testing**: Playwright (E2E), Vitest (unit - planned)
-- **Input Validation**: Robust input validation and sanitization
 
-### Key Features
+### Key Design Patterns
 
-- **Real-time Scheduling**: Live updates for VIP schedules and assignments
+- **Unified Activity Model**: Single ScheduleEvent entity for all activity types (transport, meals, meetings, events)
-- **Driver Management**: Comprehensive driver tracking and assignment
+- **Multi-VIP Support**: Activities can have multiple VIPs (`vipIds[]`) for ridesharing and group events
-- **User Roles**: Admin and driver role-based access control
+- **Soft Deletes**: All entities use `deletedAt` field for audit trail preservation
-- **Responsive Design**: Mobile-friendly interface
+- **RBAC with CASL**: Role-based access control with isomorphic permission checking
-- **Data Export**: Export capabilities for schedules and reports
+- **API Prefix**: All endpoints use `/api/v1` namespace
-- **Audit Logging**: Comprehensive activity logging
 
-## 🔍 Monitoring & Troubleshooting
+---
 
-### Health Checks
+## 📋 Features
 
-```bash
+### Core Functionality
-# Check all services
-docker-compose ps
 
-# Backend health
+**VIP Management**
-curl http://localhost:3001/health
+- Create and manage VIP profiles with arrival details
+- Track arrival mode (FLIGHT, SELF_DRIVING, OTHER)
+- Flight information integration
+- Department assignment (OFFICE_OF_DEVELOPMENT for donors, ADMIN for BSA staff)
+- Complete activity timeline per VIP
 
-# View logs
+**Activity Scheduling**
-docker-compose logs backend
+- Unified model for all activity types:
-docker-compose logs frontend
+  - 🚗 **TRANSPORT** - Airport pickups, venue shuttles, rideshares
-docker-compose logs postgres
+  - 🍽️ **MEAL** - Breakfasts, lunches, dinners, receptions
-docker-compose logs redis
+  - 📅 **EVENT** - Ceremonies, tours, campfires, presentations
+  - 🤝 **MEETING** - Donor meetings, briefings, private sessions
+  - 🏨 **ACCOMMODATION** - Check-ins, check-outs, room assignments
+- Multi-VIP assignment (e.g., "3 VIPs sharing SUV to Campfire")
+- Driver and vehicle assignment with capacity tracking
+- Conflict detection and warnings
+- Status tracking (SCHEDULED, IN_PROGRESS, COMPLETED, CANCELLED)
+
+**Search & Filtering**
+- **Real-time Search**: Instant filtering across title, location, description, VIP names, drivers, vehicles
+- **Type Filters**: Quick filter tabs (All, Transport, Meals, Events, Meetings, Accommodation)
+- **Sortable Columns**: Click to sort by Title, Type, VIPs, Start Time, or Status
+- **Combined Filtering**: Search + filters work together seamlessly
+
+**Driver & Vehicle Management**
+- Driver profiles with contact info and department
+- Vehicle tracking with type and seat capacity
+- Real-time availability checking
+- Inline driver assignment from activity list
+
+**Admin Tools**
+- One-click test data generation
+- Realistic BSA Jamboree scenarios (20 VIPs, 8 drivers, 8 vehicles, 300+ activities)
+- Balanced data: 50% OFFICE_OF_DEVELOPMENT, 50% ADMIN
+- Complete 3-day itineraries with 15 activities per VIP
+
+### User Roles & Permissions
+
+| Feature | Administrator | Coordinator | Driver |
+|---------|--------------|-------------|--------|
+| User Management | Full CRUD | View Only | None |
+| VIP Management | Full CRUD | Full CRUD | View Only |
+| Driver Management | Full CRUD | Full CRUD | View Only |
+| Activity Scheduling | Full CRUD | Full CRUD | View + Update Status |
+| Vehicle Management | Full CRUD | Full CRUD | View Only |
+| Flight Tracking | Full Access | Full Access | None |
+| Admin Tools | Full Access | Limited | None |
+
+---
+
+## 🗄️ Database Schema
+
+### Core Models
+
+**User**
+```typescript
+- auth0Sub: string (unique)
+- email: string
+- name: string
+- role: ADMINISTRATOR | COORDINATOR | DRIVER
+- isApproved: boolean (manual approval required)
+- deletedAt: DateTime? (soft delete)
 ```
 
-### Common Issues
+**VIP**
-
+```typescript
-1. **Database Connection Issues**
+- name: string
-   - Ensure PostgreSQL is healthy: `docker-compose logs postgres`
+- organization: string?
-   - Verify DATABASE_URL format
+- department: OFFICE_OF_DEVELOPMENT | ADMIN
-   - Check password special characters (avoid `!` and other special chars)
+- arrivalMode: FLIGHT | SELF_DRIVING | OTHER
-
+- expectedArrival: DateTime?
-2. **Google OAuth Issues**
+- airportPickup: boolean
-   - Verify client ID and secret
+- venueTransport: boolean
-   - Check authorized origins in Google Console
+- notes: string?
-   - Ensure callback URL matches your domain
+- flights: Flight[] (relation)
-
-3. **Frontend Not Loading**
-   - Check VITE_API_URL points to correct backend
-   - Verify backend is healthy
-   - Check browser console for errors
-
-## 🚀 Production Deployment
-
-### For Production Use
-
-1. **Use HTTPS**: Configure SSL/TLS certificates
-2. **Secure Passwords**: Use strong, unique passwords
-3. **Environment Secrets**: Use Docker secrets or external secret management
-4. **Backup Strategy**: Implement regular database backups
-5. **Monitoring**: Set up application and infrastructure monitoring
-6. **Load Balancing**: Consider load balancers for high availability
-
-### Example Production Environment
-
-```env
-# Production environment example
-POSTGRES_PASSWORD=super_secure_random_password_here
-VITE_API_URL=https://api.yourdomain.com
-VITE_FRONTEND_URL=https://yourdomain.com
-NODE_ENV=production
 ```
 
-## 📝 API Documentation
+**ScheduleEvent** (Unified Activity Model)
+```typescript
+- title: string
+- type: TRANSPORT | MEAL | EVENT | MEETING | ACCOMMODATION
+- status: SCHEDULED | IN_PROGRESS | COMPLETED | CANCELLED
+- startTime: DateTime
+- endTime: DateTime
+- location: string?
+- pickupLocation: string? (transport only)
+- dropoffLocation: string? (transport only)
+- description: string?
+- notes: string?
+- vipIds: string[] (multi-VIP support)
+- driverId: string?
+- vehicleId: string?
+```
 
-### Authentication Endpoints
+**Driver**
+```typescript
+- name: string
+- phone: string
+- department: OFFICE_OF_DEVELOPMENT | ADMIN
+- userId: string? (optional link to User)
+```
 
-- `GET /auth/google` - Initiate Google OAuth
+**Vehicle**
-- `GET /auth/google/callback` - OAuth callback
+```typescript
-- `POST /auth/logout` - Logout user
+- name: string
-- `GET /auth/me` - Get current user
+- type: VAN | SUV | SEDAN | BUS | GOLF_CART | OTHER
-
+- licensePlate: string
-### Core Endpoints
+- seatCapacity: number
-
+- status: AVAILABLE | IN_USE | MAINTENANCE
-- `GET /api/vips` - List VIPs
-- `POST /api/vips` - Create VIP
-- `GET /api/drivers` - List drivers
-- `POST /api/drivers` - Create driver
-- `GET /api/schedules` - List schedules
-- `POST /api/schedules` - Create schedule
-
-### Health & Status
-
-- `GET /health` - Application health check
-- `GET /api/status` - Detailed system status
-
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
-
-## 📄 License
-
-This project is licensed under the MIT License - see the LICENSE file for details.
-
-## 🆘 Support
-
-For issues and questions:
-
-1. Check the troubleshooting section above
-2. Review Docker Compose logs
-3. Create an issue on GitHub with:
-   - Docker Compose version
-   - Environment details
-   - Error logs
-   - Steps to reproduce
-
-## 🔄 Updates
-
-To update to the latest version:
-
-```bash
-# Pull latest images
-docker-compose pull
-
-# Restart services
-docker-compose up -d
 ```
 
 ---
 
-**Built with ❤️ for efficient VIP transportation coordination**
+## 🔐 Authentication & Security
+
+### Auth0 Integration
+
+1. **Setup Auth0 Application**
+   - Create Auth0 tenant at https://auth0.com
+   - Create a "Regular Web Application"
+   - Configure Allowed Callback URLs: `http://localhost:5173/callback`
+   - Configure Allowed Logout URLs: `http://localhost:5173`
+   - Configure Allowed Web Origins: `http://localhost:5173`
+
+2. **Configure Backend** (`backend/.env`)
+   ```env
+   AUTH0_DOMAIN=your-tenant.auth0.com
+   AUTH0_AUDIENCE=https://your-tenant.auth0.com/api/v2/
+   ```
+
+3. **Configure Frontend** (`frontend/.env`)
+   ```env
+   VITE_AUTH0_DOMAIN=your-tenant.auth0.com
+   VITE_AUTH0_CLIENT_ID=your_client_id
+   VITE_AUTH0_AUDIENCE=https://your-tenant.auth0.com/api/v2/
+   ```
+
+### User Approval Workflow
+
+**New users must be manually approved:**
+1. User registers via Auth0
+2. User account created with `isApproved: false`
+3. Administrator manually approves user
+4. User gains access to system
+
+⚠️ **First User Chicken-and-Egg Problem**: Use database seed script or manually set `isApproved: true` for first admin.
+
+### Security Features
+
+- **JWT Authentication**: Stateless token-based auth
+- **RBAC**: Role-based access control at route and UI levels
+- **API Guards**: NestJS guards enforce permissions on all endpoints
+- **Soft Deletes**: Audit trail preservation
+- **Input Validation**: DTO validation with class-validator
+- **SQL Injection Protection**: Prisma ORM parameterized queries
+
+---
+
+## 📡 API Endpoints
+
+### Authentication
+```
+POST   /api/v1/auth/login          - Auth0 login
+POST   /api/v1/auth/logout         - Logout
+GET    /api/v1/auth/me             - Get current user
+```
+
+### VIPs
+```
+GET    /api/v1/vips                - List all VIPs
+POST   /api/v1/vips                - Create VIP (Admin/Coordinator)
+GET    /api/v1/vips/:id            - Get VIP details
+PATCH  /api/v1/vips/:id            - Update VIP (Admin/Coordinator)
+DELETE /api/v1/vips/:id            - Delete VIP (Admin/Coordinator)
+GET    /api/v1/vips/:id/schedule   - Get VIP's complete itinerary
+```
+
+### Activities (ScheduleEvents)
+```
+GET    /api/v1/events              - List all activities
+POST   /api/v1/events              - Create activity (Admin/Coordinator)
+GET    /api/v1/events/:id          - Get activity details
+PATCH  /api/v1/events/:id          - Update activity (Admin/Coordinator/Driver)
+DELETE /api/v1/events/:id          - Delete activity (Admin/Coordinator)
+PATCH  /api/v1/events/:id/status   - Update activity status (Driver allowed)
+POST   /api/v1/events/:id/vips     - Add VIPs to activity
+```
+
+### Drivers
+```
+GET    /api/v1/drivers             - List all drivers
+POST   /api/v1/drivers             - Create driver (Admin/Coordinator)
+GET    /api/v1/drivers/:id         - Get driver details
+PATCH  /api/v1/drivers/:id         - Update driver (Admin/Coordinator)
+DELETE /api/v1/drivers/:id         - Delete driver (Admin/Coordinator)
+```
+
+### Vehicles
+```
+GET    /api/v1/vehicles            - List all vehicles
+POST   /api/v1/vehicles            - Create vehicle (Admin/Coordinator)
+GET    /api/v1/vehicles/:id        - Get vehicle details
+PATCH  /api/v1/vehicles/:id        - Update vehicle (Admin/Coordinator)
+DELETE /api/v1/vehicles/:id        - Delete vehicle (Admin/Coordinator)
+```
+
+### Users
+```
+GET    /api/v1/users               - List all users (Admin only)
+PATCH  /api/v1/users/:id/approve   - Approve user (Admin only)
+PATCH  /api/v1/users/:id/role      - Update user role (Admin only)
+DELETE /api/v1/users/:id           - Delete user (Admin only)
+```
+
+---
+
+## 🧪 Testing
+
+### E2E Testing with Playwright
+
+```bash
+cd frontend
+
+# Install Playwright browsers (first time only)
+npx playwright install
+
+# Run all E2E tests
+npx playwright test
+
+# Run specific test file
+npx playwright test e2e/multi-vip-events.spec.ts
+
+# Run tests in UI mode (interactive)
+npx playwright test --ui
+
+# View test report
+npx playwright show-report
+```
+
+**Test Coverage**
+- ✅ Multi-VIP event creation and management
+- ✅ Search and filtering functionality
+- ✅ Driver assignment workflows
+- ✅ Authentication flows
+- ✅ Navigation and routing
+- ✅ API integration
+- ✅ Accessibility compliance
+- ✅ iPad/tablet UI responsiveness
+
+---
+
+## 🐛 Common Issues & Solutions
+
+### Database Issues
+
+**Problem**: "Can't reach database server at localhost:5432"
+```bash
+# Start PostgreSQL (if using Docker)
+docker-compose up -d postgres
+
+# Or check if PostgreSQL is running locally
+sudo service postgresql status
+```
+
+**Problem**: "Migration failed" or "Schema drift detected"
+```bash
+cd backend
+npx prisma migrate reset  # ⚠️ Deletes all data
+npx prisma migrate deploy
+npx prisma db seed
+```
+
+### Authentication Issues
+
+**Problem**: "401 Unauthorized" on all API calls
+- Verify Auth0 domain and audience are correct in both backend and frontend `.env`
+- Check browser console for Auth0 errors
+- Verify JWT token is being sent in request headers
+- Ensure user is approved (`isApproved: true`)
+
+**Problem**: Redirect loop on login
+- Check Auth0 callback URLs match frontend URL exactly
+- Clear browser cookies and local storage
+- Verify Auth0 client ID is correct
+
+### Frontend Issues
+
+**Problem**: "Cannot read property 'map' of undefined"
+- Data not loaded yet - add loading states
+- Check React Query cache invalidation
+- Verify API endpoint returns expected data structure
+
+**Problem**: Search/sorting not working
+- Clear browser cache
+- Check console for JavaScript errors
+- Verify `filteredEvents` useMemo dependencies
+
+---
+
+## 🚀 Deployment
+
+### Production Checklist
+
+- [ ] Set `NODE_ENV=production`
+- [ ] Use strong database passwords
+- [ ] Configure Auth0 for production domain
+- [ ] Enable HTTPS/SSL certificates
+- [ ] Set up automated database backups
+- [ ] Configure Redis persistence
+- [ ] Set up monitoring (e.g., Sentry, DataDog)
+- [ ] Configure CORS for production domain
+- [ ] Review and adjust rate limiting
+- [ ] Set up log aggregation
+- [ ] Configure CDN for frontend assets (optional)
+
+### Docker Deployment
+
+```bash
+# Build images
+docker-compose build
+
+# Start all services
+docker-compose up -d
+
+# Run migrations
+docker-compose exec backend npx prisma migrate deploy
+
+# Seed database (optional)
+docker-compose exec backend npx prisma db seed
+
+# View logs
+docker-compose logs -f backend
+docker-compose logs -f frontend
+```
+
+### Environment Variables
+
+**Backend** (`backend/.env`)
+```env
+DATABASE_URL=postgresql://user:password@localhost:5432/vip_coordinator
+REDIS_URL=redis://localhost:6379
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_AUDIENCE=https://your-tenant.auth0.com/api/v2/
+NODE_ENV=production
+PORT=3000
+```
+
+**Frontend** (`frontend/.env`)
+```env
+VITE_API_URL=https://api.yourdomain.com
+VITE_AUTH0_DOMAIN=your-tenant.auth0.com
+VITE_AUTH0_CLIENT_ID=your_client_id
+VITE_AUTH0_AUDIENCE=https://your-tenant.auth0.com/api/v2/
+```
+
+---
+
+## 📚 Development Guide
+
+### Project Structure
+
+```
+vip-coordinator/
+├── backend/                  # NestJS Backend
+│   ├── prisma/
+│   │   ├── schema.prisma     # Database schema
+│   │   ├── migrations/       # Database migrations
+│   │   └── seed.ts           # Test data seeding
+│   ├── src/
+│   │   ├── auth/             # Auth0 + JWT authentication
+│   │   ├── users/            # User management
+│   │   ├── vips/             # VIP management
+│   │   ├── drivers/          # Driver management
+│   │   ├── vehicles/         # Vehicle management
+│   │   ├── events/           # Activity scheduling (ScheduleEvent)
+│   │   ├── flights/          # Flight tracking
+│   │   └── common/           # Shared utilities, guards, decorators
+│   └── package.json
+│
+├── frontend/                 # React Frontend
+│   ├── e2e/                  # Playwright E2E tests
+│   ├── src/
+│   │   ├── pages/            # Page components
+│   │   ├── components/       # Reusable UI components
+│   │   ├── contexts/         # React contexts (Auth)
+│   │   ├── hooks/            # Custom React hooks
+│   │   ├── lib/              # Utilities, API client
+│   │   └── types/            # TypeScript types
+│   ├── playwright.config.ts  # Playwright configuration
+│   └── package.json
+│
+├── docker-compose.yml        # Docker orchestration
+└── README.md                 # This file
+```
+
+### Database Migrations
+
+```bash
+# Create a new migration
+cd backend
+npx prisma migrate dev --name description_of_change
+
+# Apply migrations to production
+npx prisma migrate deploy
+
+# Reset database (⚠️ deletes all data)
+npx prisma migrate reset
+
+# View migration status
+npx prisma migrate status
+```
+
+### Adding a New Feature
+
+1. **Backend**
+   ```bash
+   cd backend
+   nest g module feature-name
+   nest g service feature-name
+   nest g controller feature-name
+   ```
+
+2. **Update Prisma Schema** (if needed)
+   ```prisma
+   model NewEntity {
+     id        String   @id @default(uuid())
+     createdAt DateTime @default(now())
+     updatedAt DateTime @updatedAt
+     deletedAt DateTime? // Soft delete
+   }
+   ```
+
+3. **Create Migration**
+   ```bash
+   npx prisma migrate dev --name add_new_entity
+   ```
+
+4. **Frontend**
+   - Create page in `frontend/src/pages/`
+   - Add route in `frontend/src/App.tsx`
+   - Create API service methods in `frontend/src/lib/api.ts`
+   - Add navigation link in `frontend/src/components/Layout.tsx`
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Write/update tests if applicable
+5. Commit with descriptive messages
+6. Push to your branch
+7. Create a Pull Request
+
+### Commit Message Format
+
+```
+<type>: <subject>
+
+<body>
+
+Co-Authored-By: Your Name <your.email@example.com>
+```
+
+**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+---
+
+## 📖 Additional Documentation
+
+- **CLAUDE.md** - Comprehensive project context for AI assistants
+- **PLAYWRIGHT_GUIDE.md** - E2E testing guide
+- **NAVIGATION_UX_IMPROVEMENTS.md** - UI/UX enhancement notes
+- **KEYCLOAK_SETUP.md** - Alternative auth setup (archived)
+
+---
+
+## 🔄 Changelog
+
+### Latest (v2.0.0) - 2026-01-31
+
+**Major Changes**
+- ✨ Unified activity system (merged Event/EventTemplate → ScheduleEvent)
+- ✨ Multi-VIP support (`vipIds[]` array for ridesharing)
+- ✨ Advanced search with real-time filtering
+- ✨ Sortable data tables (Title, Type, VIPs, Start Time, Status)
+- ✨ Balanced BSA-relevant test data
+- 🔧 Renamed "Schedule" → "Activities" throughout app
+- 🗄️ Database schema overhaul (3 new migrations)
+- 🧪 Playwright E2E test suite added
+- 📚 Complete documentation rewrite
+
+**Breaking Changes**
+- API: `vipId` → `vipIds[]` in all event endpoints
+- Database: Event/EventTemplate tables dropped
+- Migration required: `npx prisma migrate deploy`
+
+---
+
+## 📄 License
+
+This project is proprietary software developed for BSA Jamboree operations.
+
+---
+
+## 🆘 Support
+
+**For Issues:**
+1. Check this README's troubleshooting section
+2. Review logs: `docker-compose logs -f`
+3. Check CLAUDE.md for detailed context
+4. Create an issue in Gitea with:
+   - Steps to reproduce
+   - Error messages/logs
+   - Environment details
+   - Screenshots if applicable
+
+**For Questions:**
+- Review documentation files in repository root
+- Check API documentation at `/api` endpoint
+- Review Playwright test examples in `frontend/e2e/`
+
+---
+
+**Built for BSA Jamboree Operations** 🏕️