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
```bash
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](https://console.cloud.google.com/)
   - 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**:
   ```bash
   # 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**:
   ```bash
   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
```bash
# 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
```bash
# 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:
   ```bash
   cp .env.production .env.prod
   # Edit .env.prod with your secure values
   ```

### Production Deployment Steps

1. **Configure Environment Variables**:
   ```bash
   # 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**:
   ```bash
   # 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**:
   ```bash
   # 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

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

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