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

```bash
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

```bash
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

```bash
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

```bash
# 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)
```bash
curl http://localhost:3000/api/v1/health
```

### Get Profile (Requires Auth0 Token)
```bash
# 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
```bash
curl http://localhost:3000/api/v1/vips \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

---

## 🐛 Troubleshooting

### "Cannot connect to database"
```bash
# 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"
```bash
# 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](backend/README.md)

---

## 🚢 Deploy to Production

See [CLAUDE.md](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](CLAUDE.md) for comprehensive documentation
- Check [README.md](README.md) for detailed feature overview
- Check [backend/README.md](backend/README.md) for API docs
- Check [frontend/README.md](frontend/README.md) for frontend docs

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

**Last Updated:** January 25, 2026