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
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 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
# 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
make dev
Production
# Build production images
make build
# Deploy with production configuration
docker-compose -f docker-compose.prod.yml up -d
Environment Configuration
See 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
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and test thoroughly
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - 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 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.