vip-coordinator/CLAUDE.md

# VIP Coordinator - Technical Documentation

## Project Overview
VIP Transportation Coordination System - A web application for managing VIP transportation with driver assignments, real-time tracking, and user management.

## Tech Stack
- **Frontend**: React with TypeScript, Tailwind CSS
- **Backend**: Node.js with Express, TypeScript
- **Database**: PostgreSQL
- **Authentication**: Google OAuth 2.0 via Google Identity Services
- **Containerization**: Docker & Docker Compose
- **State Management**: React Context API
- **JWT**: Custom JWT Key Manager with automatic rotation

## Authentication System

### Current Implementation (Working)
We use Google Identity Services (GIS) SDK on the frontend to avoid CORS issues:

1. **Frontend-First OAuth Flow**:
   - Frontend loads Google Identity Services SDK
   - User clicks "Sign in with Google" button
   - Google shows authentication popup
   - Google returns a credential (JWT) directly to frontend
   - Frontend sends credential to backend `/auth/google/verify`
   - Backend verifies credential, creates/updates user, returns JWT

2. **Key Files**:
   - `frontend/src/components/GoogleLogin.tsx` - Google Sign-In button with GIS SDK
   - `backend/src/routes/simpleAuth.ts` - Auth endpoints including `/google/verify`
   - `backend/src/services/jwtKeyManager.ts` - JWT token generation with rotation

3. **User Flow**:
   - First user → Administrator role with status='active'
   - Subsequent users → Coordinator role with status='pending'
   - Pending users see styled waiting page until admin approval

### Important Endpoints
- `POST /auth/google/verify` - Verify Google credential and create/login user
- `GET /auth/me` - Get current user from JWT token
- `GET /auth/users/me` - Get detailed user info including status
- `GET /auth/setup` - Check if system has users

## Database Schema

### Users Table
```sql
users (
  id VARCHAR(255) PRIMARY KEY,
  google_id VARCHAR(255) UNIQUE,
  email VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(255) NOT NULL,
  role VARCHAR(50) CHECK IN ('driver', 'coordinator', 'administrator'),
  profile_picture_url TEXT,
  status VARCHAR(20) DEFAULT 'pending' CHECK IN ('pending', 'active', 'deactivated'),
  approval_status VARCHAR(20) DEFAULT 'pending' CHECK IN ('pending', 'approved', 'denied'),
  phone VARCHAR(50),
  organization VARCHAR(255),
  onboarding_data JSONB,
  approved_by VARCHAR(255),
  approved_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  last_login TIMESTAMP,
  is_active BOOLEAN DEFAULT true,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
```

## Common Issues & Solutions

### 1. CORS/Cross-Origin Issues
**Problem**: OAuth redirects and popups cause CORS errors
**Solution**: Use Google Identity Services SDK directly in frontend, send credential to backend

### 2. Missing Database Columns
**Problem**: Backend expects columns that don't exist
**Solution**: Run migrations to add missing columns:
```sql
ALTER TABLE users ADD COLUMN IF NOT EXISTS status VARCHAR(20) DEFAULT 'pending';
ALTER TABLE users ADD COLUMN IF NOT EXISTS approval_status VARCHAR(20) DEFAULT 'pending';
```

### 3. JWT Token Missing Fields
**Problem**: Frontend expects fields in JWT that aren't included
**Solution**: Update `jwtKeyManager.ts` to include all required fields (status, approval_status, etc.)

### 4. First User Not Admin
**Problem**: First user created as coordinator instead of administrator
**Solution**: Check `isFirstUser()` method properly counts users in database

### 5. Auth Routes 404
**Problem**: Frontend calling wrong API endpoints
**Solution**: Auth routes are at `/auth/*` not `/api/auth/*`

## User Management

### User Roles
- **Administrator**: Full access, can approve users, first user gets this role
- **Coordinator**: Can manage VIPs and drivers, needs admin approval
- **Driver**: Can view assigned trips, needs admin approval
- **Viewer**: Read-only access (if implemented)

### User Status Flow
1. User signs in with Google → Created with status='pending'
2. Admin approves → Status changes to 'active'
3. Admin can deactivate → Status changes to 'deactivated'

### Approval System
- First user is auto-approved as administrator
- All other users need admin approval
- Pending users see a styled waiting page
- Page auto-refreshes every 30 seconds to check approval

## Docker Setup

### Environment Variables
Create `.env` file with:
```
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=https://yourdomain.com/auth/google/callback
FRONTEND_URL=https://yourdomain.com
DB_PASSWORD=your-secure-password
```

### Running the System
```bash
docker-compose up -d
```

Services:
- Frontend: http://localhost:5173
- Backend: http://localhost:3000
- PostgreSQL: localhost:5432
- Redis: localhost:6379

## Key Learnings

1. **Google OAuth Strategy**: Frontend-first approach with GIS SDK avoids CORS issues entirely
2. **JWT Management**: Custom JWT manager with key rotation provides better security
3. **Database Migrations**: Always check table schema matches backend expectations
4. **User Experience**: Clear, styled feedback for pending users improves perception
5. **Error Handling**: Proper error messages and status codes help debugging
6. **Docker Warnings**: POSTGRES_PASSWORD warnings are cosmetic and don't affect functionality

## Future Improvements

1. Email notifications when users are approved
2. Role-based UI components (hide/show based on user role)
3. Audit logging for all admin actions
4. Batch user approval interface
5. Password-based login as fallback
6. User profile editing
7. Organization-based access control