vip-coordinator/QUICKSTART.md

VIP Coordinator - Quick Start Guide

🚀 Get Started in 5 Minutes

Prerequisites

• Node.js 20+
• Docker Desktop
• Auth0 Account (free tier at https://auth0.com)

Step 1: Start Database

cd vip-coordinator
docker-compose up -d postgres

Step 2: Configure Auth0

1. Go to https://auth0.com and create a free account

2. Create a new Application (Single Page Application)

3. Create a new API

4. Note your credentials:

   • Domain: your-tenant.us.auth0.com
   • Client ID: abc123...
   • Audience: https://your-api-identifier

5. Configure callback URLs in Auth0 dashboard:

   • Allowed Callback URLs: http://localhost:5173/callback
   • Allowed Logout URLs: http://localhost:5173
   • Allowed Web Origins: http://localhost:5173

Step 3: Configure Backend

cd backend

# Edit .env file
# Replace these with your Auth0 credentials:
AUTH0_DOMAIN="your-tenant.us.auth0.com"
AUTH0_AUDIENCE="https://your-api-identifier"
AUTH0_ISSUER="https://your-tenant.us.auth0.com/"

# Install and setup
npm install
npx prisma generate
npx prisma migrate dev
npm run prisma:seed

Step 4: Configure Frontend

cd ../frontend

# Edit .env file
# Replace these with your Auth0 credentials:
VITE_AUTH0_DOMAIN="your-tenant.us.auth0.com"
VITE_AUTH0_CLIENT_ID="your-client-id"
VITE_AUTH0_AUDIENCE="https://your-api-identifier"

# Already installed during build
# npm install (only if not already done)

Step 5: Start Everything

# Terminal 1: Backend
cd backend
npm run start:dev

# Terminal 2: Frontend
cd frontend
npm run dev

Step 6: Access the App

Open your browser to: http://localhost:5173

1. Click "Sign In with Auth0"
2. Create an account or sign in
3. First user becomes Administrator automatically!
4. Explore the dashboard

---

🎯 What You Get

Backend API (http://localhost:3000/api/v1)

• ✅ Auth0 Authentication - Secure JWT-based auth
• ✅ User Management - Approval workflow for new users
• ✅ VIP Management - Complete CRUD with relationships
• ✅ Driver Management - Driver profiles and schedules
• ✅ Event Scheduling - Smart conflict detection
• ✅ Flight Tracking - Real-time flight status (AviationStack API)
• ✅ 40+ API Endpoints - Fully documented REST API
• ✅ Role-Based Access - Administrator, Coordinator, Driver
• ✅ Sample Data - Pre-loaded test data

Frontend (http://localhost:5173)

• ✅ Modern React UI - React 18 + TypeScript
• ✅ Tailwind CSS - Beautiful, responsive design
• ✅ Auth0 Integration - Seamless authentication
• ✅ TanStack Query - Smart data fetching and caching
• ✅ Dashboard - Overview with stats and recent activity
• ✅ VIP Management - List, view, create, edit VIPs
• ✅ Driver Management - Manage driver profiles
• ✅ Schedule View - See all events and assignments
• ✅ Protected Routes - Automatic authentication checks

---

📊 Sample Data

The database is seeded with:

• 2 Users: admin@example.com, coordinator@example.com
• 2 VIPs: Dr. Robert Johnson (flight), Ms. Sarah Williams (self-driving)
• 2 Drivers: John Smith, Jane Doe
• 3 Events: Airport pickup, welcome dinner, conference transport

---

🔑 User Roles

Administrator

• Full system access
• Can approve/deny new users
• Can manage all VIPs, drivers, events

Coordinator

• Can manage VIPs, drivers, events
• Cannot manage users
• Full scheduling access

Driver

• View assigned schedules
• Update event status
• Cannot create or delete

First user to register = Administrator (no manual setup needed!)

---

🧪 Testing the API

Health Check (Public)

curl http://localhost:3000/api/v1/health

Get Profile (Requires Auth0 Token)

# Get token from browser DevTools -> Application -> Local Storage -> auth0_token
curl http://localhost:3000/api/v1/auth/profile \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

List VIPs

curl http://localhost:3000/api/v1/vips \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

---

🐛 Troubleshooting

"Cannot connect to database"

# Check PostgreSQL is running
docker ps | grep postgres

# Should see: vip-postgres running on port 5433

"Auth0 redirect loop"

• Check your .env files have correct Auth0 credentials
• Verify callback URLs in Auth0 dashboard match http://localhost:5173/callback
• Clear browser cache and cookies

"Cannot find module"

# Backend
cd backend
npx prisma generate
npm run build

# Frontend
cd frontend
npm install

"Port already in use"

• Backend uses port 3000
• Frontend uses port 5173
• PostgreSQL uses port 5433

Close any processes using these ports.

---

📚 Next Steps

1. Explore the Dashboard - See stats and recent activity
2. Add a VIP - Try creating a new VIP profile
3. Assign a Driver - Schedule an event with driver assignment
4. Test Conflict Detection - Try double-booking a driver
5. Approve Users - Have someone else sign up, then approve them as admin
6. View API Docs - Check backend/README.md

---

🚢 Deploy to Production

See CLAUDE.md for Digital Ocean deployment instructions.

Ready to deploy:

• ✅ Docker Compose configuration
• ✅ Production environment variables
• ✅ Optimized builds
• ✅ Auth0 production setup guide

---

Need Help?

• Check CLAUDE.md for comprehensive documentation
• Check BUILD_STATUS.md for what's implemented
• Check backend/README.md for API docs
• Check frontend/README.md for frontend docs

Built with: NestJS, React, TypeScript, Prisma, PostgreSQL, Auth0, Tailwind CSS

Last Updated: January 25, 2026