vip-coordinator/SETUP_GUIDE.md

VIP Coordinator Setup Guide

A comprehensive guide to set up and run the VIP Coordinator system.

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Google Cloud Console account (for OAuth)

1. Clone and Start

git clone <repository-url>
cd vip-coordinator
make dev

The application will be available at:

• Frontend: http://localhost:5173
• Backend API: http://localhost:3000
• API Documentation: http://localhost:3000/api-docs.html

2. Google OAuth Setup (Required)

1. Create Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project or select existing one

2. Enable Google+ API:

   • Navigate to "APIs & Services" > "Library"
   • Search for "Google+ API" and enable it

3. Create OAuth Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth 2.0 Client IDs"
   • Application type: "Web application"
   • Authorized redirect URIs: http://localhost:3000/auth/google/callback

4. Configure Environment:

   # Copy the example environment file
   cp backend/.env.example backend/.env
   
   # Edit backend/.env and add your Google OAuth credentials:
   GOOGLE_CLIENT_ID=your-client-id-here
   GOOGLE_CLIENT_SECRET=your-client-secret-here
   

5. Restart the Application:

   make dev
   

3. First Login

• Visit http://localhost:5173
• Click "Continue with Google"
• The first user to log in becomes the system administrator
• Subsequent users need administrator approval

🏗️ Architecture Overview

Authentication System

• JWT-based authentication with Google OAuth
• Role-based access control: Administrator, Coordinator, Driver
• User approval system for new registrations
• Simple setup - no complex OAuth configurations needed

Database

• PostgreSQL for persistent data storage
• Automatic schema initialization on first run
• User management with approval workflows
• VIP and driver data with scheduling

API Structure

• RESTful API with comprehensive endpoints
• OpenAPI/Swagger documentation at /api-docs.html
• Role-based endpoint protection
• Real-time flight tracking integration

📋 Features

Current Features

• ✅ User Management: Google OAuth with role-based access
• ✅ VIP Management: Create, edit, track VIPs with flight information
• ✅ Driver Coordination: Manage drivers and assignments
• ✅ Flight Tracking: Real-time flight status updates
• ✅ Schedule Management: Event scheduling with conflict detection
• ✅ Department Support: Office of Development and Admin departments
• ✅ API Documentation: Interactive Swagger UI

User Roles

• Administrator: Full system access, user management
• Coordinator: VIP and driver management, scheduling
• Driver: View assigned schedules (planned)

🔧 Configuration

Environment Variables

# Database
DATABASE_URL=postgresql://vip_user:vip_password@db:5432/vip_coordinator

# Authentication
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
JWT_SECRET=your-jwt-secret-key

# External APIs (Optional)
AVIATIONSTACK_API_KEY=your-aviationstack-key

# Application
FRONTEND_URL=http://localhost:5173
PORT=3000

Docker Services

• Frontend: React + Vite development server
• Backend: Node.js + Express API server
• Database: PostgreSQL with automatic initialization
• Redis: Caching and real-time updates

🛠️ Development

Available Commands

# Start development environment
make dev

# View logs
make logs

# Stop all services
make down

# Rebuild containers
make build

# Backend only
cd backend && npm run dev

# Frontend only
cd frontend && npm run dev

API Testing

• Interactive Documentation: http://localhost:3000/api-docs.html
• Health Check: http://localhost:3000/api/health
• Authentication Test: Use the "Try it out" feature in Swagger UI

🔐 Security

Authentication Flow

1. User clicks "Continue with Google"
2. Redirected to Google OAuth
3. Google redirects back with authorization code
4. Backend exchanges code for user info
5. JWT token generated and returned
6. Frontend stores token for API requests

API Protection

• All API endpoints require valid JWT token
• Role-based access control on sensitive operations
• User approval system for new registrations

📚 API Documentation

Key Endpoints

• Authentication: /auth/* - OAuth and user management
• VIPs: /api/vips/* - VIP management and scheduling
• Drivers: /api/drivers/* - Driver management and availability
• Flights: /api/flights/* - Flight tracking and information
• Admin: /api/admin/* - System administration

Interactive Documentation

Visit http://localhost:3000/api-docs.html for:

• Complete API reference
• Request/response examples
• "Try it out" functionality
• Schema definitions

🚨 Troubleshooting

Common Issues

OAuth Not Working:

• Verify Google Client ID and Secret in .env
• Check redirect URI in Google Console matches exactly
• Ensure Google+ API is enabled

Database Connection Error:

• Verify Docker containers are running: docker ps
• Check database logs: docker-compose logs db
• Restart services: make down && make dev

Frontend Can't Connect to Backend:

• Verify backend is running on port 3000
• Check CORS configuration in backend
• Ensure FRONTEND_URL is set correctly

Getting Help

1. Check the interactive API documentation
2. Review Docker container logs
3. Verify environment configuration
4. Test with the health check endpoint

🔄 Production Deployment

Prerequisites for Production

1. Domain Setup: Ensure your domains are configured:

   • Frontend: https://bsa.madeamess.online
   • API: https://api.bsa.madeamess.online

2. SSL Certificates: Configure SSL/TLS certificates for your domains

3. Environment Configuration: Copy and configure production environment:

   cp .env.production .env.prod
   # Edit .env.prod with your secure values
   

Production Deployment Steps

1. Configure Environment Variables:

   # Edit .env.prod with secure values:
   # - Change DB_PASSWORD to a strong password
   # - Generate new JWT_SECRET and SESSION_SECRET
   # - Update ADMIN_PASSWORD
   # - Set your AVIATIONSTACK_API_KEY
   

2. Deploy with Production Configuration:

   # Load production environment
   export $(cat .env.prod | xargs)
   
   # Build and start production containers
   docker-compose -f docker-compose.prod.yml up -d --build
   

3. Verify Deployment:

   # Check container status
   docker-compose -f docker-compose.prod.yml ps
   
   # View logs
   docker-compose -f docker-compose.prod.yml logs
   

Production vs Development Differences

Feature	Development	Production
Build Target	development	production
Source Code	Volume mounted (hot reload)	Built into image
Database Password	Hardcoded changeme	Environment variable
Frontend Server	Vite dev server (port 5173)	Nginx (port 80)
API URL	http://localhost:3000/api	https://api.bsa.madeamess.online/api
SSL/HTTPS	Not configured	Required
Restart Policy	Manual	unless-stopped

Production Environment Variables

# Database Configuration
DB_PASSWORD=your-secure-database-password-here

# Domain Configuration
DOMAIN=bsa.madeamess.online
VITE_API_URL=https://api.bsa.madeamess.online/api

# Authentication Configuration (Generate new secure keys)
JWT_SECRET=your-super-secure-jwt-secret-key-change-in-production-12345
SESSION_SECRET=your-super-secure-session-secret-change-in-production-67890

# Google OAuth Configuration
GOOGLE_CLIENT_ID=308004695553-6k34bbq22frc4e76kejnkgq8mncepbbg.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=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
GOOGLE_REDIRECT_URI=https://api.bsa.madeamess.online/auth/google/callback

# Frontend URL
FRONTEND_URL=https://bsa.madeamess.online

# Flight API Configuration
AVIATIONSTACK_API_KEY=your-aviationstack-api-key

# Admin Configuration
ADMIN_PASSWORD=your-secure-admin-password

# Port Configuration
PORT=3000

Production-Specific Troubleshooting

SSL Certificate errors: Ensure certificates are properly configured Domain resolution: Verify DNS settings for your domains Environment variables: Check that all required variables are set in .env.prod Firewall: Ensure ports 80, 443, 3000 are accessible

Production Logs

# View production container logs
docker-compose -f docker-compose.prod.yml logs backend
docker-compose -f docker-compose.prod.yml logs frontend
docker-compose -f docker-compose.prod.yml logs db

# Follow logs in real-time
docker-compose -f docker-compose.prod.yml logs -f

This setup guide reflects the current simple, effective architecture of the VIP Coordinator system with production-ready deployment capabilities.