vip-coordinator/README.md

# VIP Coordinator

A comprehensive web application for managing VIP logistics, driver assignments, and real-time tracking with Google OAuth authentication and role-based access control.

## ✨ Features

### 🔐 Authentication & User Management
- **Google OAuth Integration**: Secure login with Google accounts
- **Role-Based Access Control**: Administrator, Coordinator, and Driver roles
- **User Approval System**: Admin approval required for new users
- **JWT-Based Authentication**: Stateless, secure token system

### 👥 VIP Management
- **Complete VIP Profiles**: Name, organization, department, transport details
- **Multi-Flight Support**: Handle complex itineraries with multiple flights
- **Department Organization**: Office of Development and Admin departments
- **Schedule Management**: Event scheduling with conflict detection
- **Real-time Flight Tracking**: Automatic flight status updates

### 🚗 Driver Coordination
- **Driver Management**: Create and manage driver profiles
- **Availability Checking**: Real-time conflict detection
- **Schedule Assignment**: Assign drivers to VIP events
- **Department-Based Organization**: Organize drivers by department

### ✈️ Flight Integration
- **Real-time Flight Data**: Integration with AviationStack API
- **Automatic Tracking**: Scheduled flight status updates
- **Multi-Flight Support**: Handle complex travel itineraries
- **Flight Validation**: Verify flight numbers and dates

### 📊 Advanced Features
- **Interactive API Documentation**: Swagger UI with "Try it out" functionality
- **Schedule Validation**: Prevent conflicts and overlapping assignments
- **Comprehensive Logging**: Detailed system activity tracking
- **Docker Containerization**: Easy deployment and development

## 🏗️ Architecture

### Backend
- **Node.js + Express.js**: RESTful API server
- **TypeScript**: Full type safety
- **PostgreSQL**: Persistent data storage with automatic schema management
- **Redis**: Caching and real-time updates
- **JWT Authentication**: Secure, stateless authentication
- **Google OAuth 2.0**: Simple, secure user authentication

### Frontend
- **React 18 + TypeScript**: Modern, type-safe frontend
- **Vite**: Lightning-fast development server
- **Tailwind CSS v4**: Modern utility-first styling
- **React Router**: Client-side routing
- **Responsive Design**: Mobile-friendly interface

## 🚀 Quick Start

### Prerequisites
- Docker and Docker Compose
- Google Cloud Console account (for OAuth setup)

### 1. Start the Application
```bash
git clone <repository-url>
cd vip-coordinator
make dev
```

**Services will be available at:**
- 🌐 **Frontend**: http://localhost:5173
- 🔌 **Backend API**: http://localhost:3000
- 📚 **API Documentation**: http://localhost:3000/api-docs.html
- 🏥 **Health Check**: http://localhost:3000/api/health

### 2. Configure Google OAuth
See [SETUP_GUIDE.md](SETUP_GUIDE.md) for detailed OAuth setup instructions.

### 3. First Login
- Visit http://localhost:5173
- Click "Continue with Google"
- First user becomes system administrator
- Subsequent users need admin approval

## 📚 API Documentation

### Interactive Documentation
Visit **http://localhost:3000/api-docs.html** for:
- 📖 Complete API reference with examples
- 🧪 "Try it out" functionality for testing endpoints
- 📋 Request/response schemas and validation rules
- 🔐 Authentication requirements for each endpoint

### Key API Categories
- **🔐 Authentication**: `/auth/*` - OAuth, user management, role assignment
- **👥 VIPs**: `/api/vips/*` - VIP profiles, scheduling, flight integration
- **🚗 Drivers**: `/api/drivers/*` - Driver management, availability, conflicts
- **✈️ Flights**: `/api/flights/*` - Flight tracking, real-time updates
- **⚙️ Admin**: `/api/admin/*` - System settings, user approval

## 🛠️ Development

### Available Commands
```bash
# Start development environment
make dev

# View logs
make logs

# Stop all services
make down

# Rebuild containers
make build

# Backend development
cd backend && npm run dev

# Frontend development
cd frontend && npm run dev
```

### Project Structure
```
vip-coordinator/
├── backend/                 # Node.js API server
│   ├── src/
│   │   ├── routes/         # API route handlers
│   │   ├── services/       # Business logic services
│   │   ├── config/         # Configuration and auth
│   │   └── index.ts        # Main server file
│   ├── package.json
│   ├── tsconfig.json
│   └── Dockerfile
├── frontend/               # React frontend
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/         # Page components
│   │   ├── config/        # API configuration
│   │   ├── App.tsx        # Main app component
│   │   └── main.tsx       # Entry point
│   ├── package.json
│   ├── vite.config.ts
│   └── Dockerfile
├── docker-compose.dev.yml  # Development environment
├── docker-compose.prod.yml # Production environment
├── Makefile               # Development commands
├── SETUP_GUIDE.md         # Detailed setup instructions
└── README.md              # This file
```

## 🔐 User Roles & Permissions

### Administrator
- Full system access
- User management and approval
- System configuration
- All VIP and driver operations

### Coordinator
- VIP management (create, edit, delete)
- Driver management
- Schedule management
- Flight tracking

### Driver
- View assigned schedules
- Update task status
- Access driver dashboard

## 🌐 Deployment

### Development
```bash
make dev
```

### Production
```bash
# Build production images
make build

# Deploy with production configuration
docker-compose -f docker-compose.prod.yml up -d
```

### Environment Configuration
See [SETUP_GUIDE.md](SETUP_GUIDE.md) for detailed environment variable configuration.

## 📋 Current Status

### ✅ Implemented Features
- Google OAuth authentication with JWT
- Role-based access control
- User approval workflow
- VIP management with multi-flight support
- Driver management and scheduling
- Real-time flight tracking
- Schedule conflict detection
- Interactive API documentation
- Docker containerization
- PostgreSQL data persistence

### 🚧 Planned Features
- [ ] Real-time GPS tracking for drivers
- [ ] Push notifications for schedule changes
- [ ] Mobile driver application
- [ ] Advanced reporting and analytics
- [ ] Google Sheets integration
- [ ] Multi-tenant support
- [ ] Advanced mapping features

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and test thoroughly
4. Commit your changes: `git commit -m 'Add amazing feature'`
5. Push to the branch: `git push origin feature/amazing-feature`
6. Submit a pull request

## 📄 License

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

## 🆘 Support

- 📖 **Documentation**: Check [SETUP_GUIDE.md](SETUP_GUIDE.md) for detailed setup
- 🔧 **API Reference**: Visit http://localhost:3000/api-docs.html
- 🐛 **Issues**: Report bugs and request features via GitHub issues
- 💬 **Discussions**: Use GitHub discussions for questions and ideas

---

**VIP Coordinator** - Streamlining VIP logistics with modern web technology.