From ba5aa4731a82274688571cdc7a46578aa8d31c2e Mon Sep 17 00:00:00 2001 From: kyle Date: Sat, 31 Jan 2026 16:47:27 +0100 Subject: [PATCH] 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 --- README.md | 879 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 604 insertions(+), 275 deletions(-) diff --git a/README.md b/README.md index 90cb7c5..63ef240 100644 --- a/README.md +++ b/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 -- Google OAuth credentials (for authentication) -- Domain name or localhost for development +- **Node.js** 18+ and npm +- **PostgreSQL** 16+ +- **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 -docker pull t72chevy/vip-coordinator:frontend-latest +# Clone the repository +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**: Node.js/Express API server with TypeScript -- **Database**: PostgreSQL for persistent data storage -- **Cache**: Redis for session management and real-time features +**Backend** +- **Framework**: NestJS 11 (TypeScript) +- **Database**: PostgreSQL 16 with Prisma ORM 7.3 +- **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 -- **Google OAuth**: Secure authentication via Google -- **Non-Root Containers**: All containers run as non-root users -- **Health Checks**: Comprehensive health monitoring -- **Input Validation**: Robust input validation and sanitization +**Infrastructure** +- **Containerization**: Docker + Docker Compose +- **Database Migrations**: Prisma Migrate +- **Testing**: Playwright (E2E), Vitest (unit - planned) -### Key Features +### Key Design Patterns -- **Real-time Scheduling**: Live updates for VIP schedules and assignments -- **Driver Management**: Comprehensive driver tracking and assignment -- **User Roles**: Admin and driver role-based access control -- **Responsive Design**: Mobile-friendly interface -- **Data Export**: Export capabilities for schedules and reports -- **Audit Logging**: Comprehensive activity logging +- **Unified Activity Model**: Single ScheduleEvent entity for all activity types (transport, meals, meetings, events) +- **Multi-VIP Support**: Activities can have multiple VIPs (`vipIds[]`) for ridesharing and group events +- **Soft Deletes**: All entities use `deletedAt` field for audit trail preservation +- **RBAC with CASL**: Role-based access control with isomorphic permission checking +- **API Prefix**: All endpoints use `/api/v1` namespace -## ๐Ÿ” Monitoring & Troubleshooting +--- -### Health Checks +## ๐Ÿ“‹ Features -```bash -# Check all services -docker-compose ps +### Core Functionality -# Backend health -curl http://localhost:3001/health +**VIP Management** +- 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 -docker-compose logs backend -docker-compose logs frontend -docker-compose logs postgres -docker-compose logs redis +**Activity Scheduling** +- Unified model for all activity types: + - ๐Ÿš— **TRANSPORT** - Airport pickups, venue shuttles, rideshares + - ๐Ÿฝ๏ธ **MEAL** - Breakfasts, lunches, dinners, receptions + - ๐Ÿ“… **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 - -1. **Database Connection Issues** - - Ensure PostgreSQL is healthy: `docker-compose logs postgres` - - Verify DATABASE_URL format - - Check password special characters (avoid `!` and other special chars) - -2. **Google OAuth Issues** - - Verify client ID and secret - - Check authorized origins in Google Console - - Ensure callback URL matches your domain - -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 +**VIP** +```typescript +- name: string +- organization: string? +- department: OFFICE_OF_DEVELOPMENT | ADMIN +- arrivalMode: FLIGHT | SELF_DRIVING | OTHER +- expectedArrival: DateTime? +- airportPickup: boolean +- venueTransport: boolean +- notes: string? +- flights: Flight[] (relation) ``` -## ๐Ÿ“ 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 -- `GET /auth/google/callback` - OAuth callback -- `POST /auth/logout` - Logout user -- `GET /auth/me` - Get current user - -### Core Endpoints - -- `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 +**Vehicle** +```typescript +- name: string +- type: VAN | SUV | SEDAN | BUS | GOLF_CART | OTHER +- licensePlate: string +- seatCapacity: number +- status: AVAILABLE | IN_USE | MAINTENANCE ``` --- -**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 + +``` +: + + + +Co-Authored-By: Your Name +``` + +**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** ๐Ÿ•๏ธ