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

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:

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

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