vip-coordinator/README.md

# VIP Coordinator

A comprehensive VIP transportation coordination system built with React, Node.js, PostgreSQL, and Redis. This application provides real-time scheduling, driver management, and VIP coordination capabilities with enterprise-grade security and scalability.

## 🚀 Quick Start with Docker

### Prerequisites

- Docker and Docker Compose installed
- Google OAuth credentials (for authentication)
- Domain name or localhost for development

### 1. Pull the Images

```bash
docker pull t72chevy/vip-coordinator:backend-latest
docker pull t72chevy/vip-coordinator:frontend-latest
```

### 2. Create Environment File

Create a `.env` file in your project directory:

```env
# Database Configuration
POSTGRES_DB=vip_coordinator
POSTGRES_USER=vip_user
POSTGRES_PASSWORD=your_secure_password_here

# Backend Configuration
DATABASE_URL=postgresql://vip_user:your_secure_password_here@postgres:5432/vip_coordinator
NODE_ENV=production
PORT=3000

# Frontend Configuration
VITE_API_URL=http://localhost:3000
VITE_FRONTEND_URL=http://localhost

# Google OAuth Configuration
GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here

# Redis Configuration
REDIS_URL=redis://redis:6379

# Security
JWT_SECRET=auto-generated-on-startup
```

### 3. Create Docker Compose File

Create a `docker-compose.yml` file:

```yaml
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  backend:
    image: t72chevy/vip-coordinator:backend-latest
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - NODE_ENV=${NODE_ENV}
      - PORT=${PORT}
      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
      - REDIS_URL=${REDIS_URL}
      - JWT_SECRET=${JWT_SECRET}
    ports:
      - "3000:3000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  frontend:
    image: t72chevy/vip-coordinator:frontend-latest
    environment:
      - VITE_API_URL=${VITE_API_URL}
      - VITE_FRONTEND_URL=${VITE_FRONTEND_URL}
    ports:
      - "80:80"
    depends_on:
      backend:
        condition: service_healthy

volumes:
  postgres_data:
```

### 4. Deploy the Application

```bash
# Start all services
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f
```

### 5. Access the Application

- **Frontend**: http://localhost
- **Backend API**: http://localhost:3001
- **Health Check**: http://localhost:3001/health

## 🔧 Configuration

### Google OAuth Setup

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the Google+ API
4. Create OAuth 2.0 credentials
5. Add your domain to authorized origins
6. Add your callback URL: `http://your-domain/auth/google/callback`

### Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `POSTGRES_DB` | PostgreSQL database name | Yes | `vip_coordinator` |
| `POSTGRES_USER` | PostgreSQL username | Yes | `vip_user` |
| `POSTGRES_PASSWORD` | PostgreSQL password | Yes | - |
| `DATABASE_URL` | Full database connection string | Yes | - |
| `GOOGLE_CLIENT_ID` | Google OAuth client ID | Yes | - |
| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret | Yes | - |
| `REDIS_URL` | Redis connection string | Yes | `redis://redis:6379` |
| `NODE_ENV` | Node.js environment | No | `production` |
| `PORT` | Backend server port | No | `3001` |
| `VITE_API_URL` | Frontend API URL | Yes | - |
| `VITE_FRONTEND_URL` | Frontend base URL | Yes | - |

## 🏗️ Architecture

### Services

- **Frontend**: React application with Vite build system, served by Nginx
- **Backend**: Node.js/Express API server with TypeScript
- **Database**: PostgreSQL for persistent data storage
- **Cache**: Redis for session management and real-time features

### Security Features

- **JWT Auto-Rotation**: Automatic JWT secret rotation for enhanced security
- **Google OAuth**: Secure authentication via Google
- **Non-Root Containers**: All containers run as non-root users
- **Health Checks**: Comprehensive health monitoring
- **Input Validation**: Robust input validation and sanitization

### Key Features

- **Real-time Scheduling**: Live updates for VIP schedules and assignments
- **Driver Management**: Comprehensive driver tracking and assignment
- **User Roles**: Admin and driver role-based access control
- **Responsive Design**: Mobile-friendly interface
- **Data Export**: Export capabilities for schedules and reports
- **Audit Logging**: Comprehensive activity logging

## 🔍 Monitoring & Troubleshooting

### Health Checks

```bash
# Check all services
docker-compose ps

# Backend health
curl http://localhost:3001/health

# View logs
docker-compose logs backend
docker-compose logs frontend
docker-compose logs postgres
docker-compose logs redis
```

### Common Issues

1. **Database Connection Issues**
   - Ensure PostgreSQL is healthy: `docker-compose logs postgres`
   - Verify DATABASE_URL format
   - Check password special characters (avoid `!` and other special chars)

2. **Google OAuth Issues**
   - Verify client ID and secret
   - Check authorized origins in Google Console
   - Ensure callback URL matches your domain

3. **Frontend Not Loading**
   - Check VITE_API_URL points to correct backend
   - Verify backend is healthy
   - Check browser console for errors

## 🚀 Production Deployment

### For Production Use

1. **Use HTTPS**: Configure SSL/TLS certificates
2. **Secure Passwords**: Use strong, unique passwords
3. **Environment Secrets**: Use Docker secrets or external secret management
4. **Backup Strategy**: Implement regular database backups
5. **Monitoring**: Set up application and infrastructure monitoring
6. **Load Balancing**: Consider load balancers for high availability

### Example Production Environment

```env
# Production environment example
POSTGRES_PASSWORD=super_secure_random_password_here
VITE_API_URL=https://api.yourdomain.com
VITE_FRONTEND_URL=https://yourdomain.com
NODE_ENV=production
```

## 📝 API Documentation

### Authentication Endpoints

- `GET /auth/google` - Initiate Google OAuth
- `GET /auth/google/callback` - OAuth callback
- `POST /auth/logout` - Logout user
- `GET /auth/me` - Get current user

### Core Endpoints

- `GET /api/vips` - List VIPs
- `POST /api/vips` - Create VIP
- `GET /api/drivers` - List drivers
- `POST /api/drivers` - Create driver
- `GET /api/schedules` - List schedules
- `POST /api/schedules` - Create schedule

### Health & Status

- `GET /health` - Application health check
- `GET /api/status` - Detailed system status

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🆘 Support

For issues and questions:

1. Check the troubleshooting section above
2. Review Docker Compose logs
3. Create an issue on GitHub with:
   - Docker Compose version
   - Environment details
   - Error logs
   - Steps to reproduce

## 🔄 Updates

To update to the latest version:

```bash
# Pull latest images
docker-compose pull

# Restart services
docker-compose up -d
```

---

**Built with ❤️ for efficient VIP transportation coordination**