vip-coordinator/docs/REQUIREMENTS.md

VIP Coordinator - Requirements Document

Application Purpose

The VIP Coordinator is a web application for managing VIP transportation logistics and event coordination. Organizations use it to coordinate VIP arrivals, manage driver resources, track flight statuses, and schedule events.

---

Core Features

1. VIP Management

The application must allow users to create and manage VIP profiles.

Required Functionality:

• Create VIP profiles with: name, organization, department
• Support two transportation modes:
  • Flight: VIPs arriving by air
  • Self-driving: VIPs arriving by car
• For flight arrivals: Support multiple flight segments per VIP (e.g., JFK → LAX → SFO)
• For self-driving arrivals: Track expected arrival time
• Organize VIPs by department (Office of Development, Admin)
• Store notes and special requirements:
  • Airport pickup needed (yes/no)
  • Venue transportation needed (yes/no)
  • General notes

Required Operations:

• Create new VIP
• View list of all VIPs
• View VIP details
• Update VIP information
• Delete VIP

---

2. Driver Management

The application must allow users to manage driver resources.

Required Functionality:

• Create driver profiles with: name, phone number, department
• Link drivers to user accounts (optional - a driver can be a system user)
• View driver's complete schedule across all VIP assignments
• Organize drivers by department

Required Operations:

• Create new driver
• View list of all drivers
• View driver details
• View driver's complete schedule
• Update driver information
• Delete driver

---

3. Schedule Management

The application must allow users to create and manage events for VIPs.

Required Functionality:

• Create events for VIPs with the following types:
  • Transport
  • Meeting
  • Event
  • Meal
  • Accommodation
• Event details must include:
  • Title
  • Location
  • Start time
  • End time
  • Description (optional)
  • Assigned driver
• Event status tracking:
  • Scheduled
  • In-progress
  • Completed
  • Cancelled
• Conflict prevention:
  • Prevent double-booking drivers (same driver cannot be assigned to overlapping time slots)
  • Validate that required fields are provided
  • Check driver availability before assignment

Required Operations:

• Create event for a VIP
• View schedule for a VIP
• View schedule for a driver
• Update event details
• Update event status
• Delete event
• Check driver availability for a time slot
• Check for conflicts when assigning a driver

---

4. Flight Tracking

The application must track real-time flight status for VIPs arriving by air.

Required Functionality:

• Integrate with a flight data API (AviationStack or equivalent)
• Track multiple flights per VIP (multi-segment itineraries)
• Store flight information:
  • Flight number
  • Flight date
  • Segment number (for multi-flight itineraries)
  • Departure airport code
  • Arrival airport code
  • Scheduled departure time
  • Scheduled arrival time
  • Actual departure time (updated automatically)
  • Actual arrival time (updated automatically)
  • Flight status (scheduled, delayed, landed, etc.)
• Automatically update flight status via background jobs
• Validate flight numbers and dates

Required Operations:

• Look up flight information by flight number and date
• Batch lookup for multiple flights
• Automatically update flight statuses in the background
• Display flight status in VIP details

---

5. User Authentication & Authorization

The application must control access through authentication and role-based permissions.

Required Functionality:

• Authenticate users via OAuth (Auth0 or equivalent)
• Support three user roles:
  • Administrator: Full system access including user management
  • Coordinator: Can manage VIPs, drivers, and schedules (cannot manage users)
  • Driver: Can view assigned schedules and update event statuses only
• First user to register becomes Administrator automatically
• New users require Administrator approval before accessing the system
• User approval workflow:
  • New users start with "pending" status
  • Administrator can approve or deny users
  • Only approved users can access the application

Required Operations:

• User login/logout
• View current user information
• List all users (Administrator only)
• View user details (Administrator only)
• Approve/deny pending users (Administrator only)
• Update user roles (Administrator only)
• Delete users (Administrator only)

Permission Matrix:

Feature	Administrator	Coordinator	Driver
User Management	✅ Full	❌ None	❌ None
VIP Management	✅ Full CRUD	✅ Full CRUD	❌ View only
Driver Management	✅ Full CRUD	✅ Full CRUD	❌ View only
Schedule Management	✅ Full CRUD	✅ Full CRUD	✅ View + Update status
Flight Tracking	✅ Full	✅ Full	❌ None

---

Technical Constraints

Must Use

• PostgreSQL - Database system
• Docker - For local development environment
• TypeScript - Programming language
• React - Frontend framework

Should Use

• Auth0 - Authentication provider (preferred, but open to alternatives if better)
• Redis - Caching and background job processing

Cannot Use

• Keycloak - Not acceptable

---

Data Model Requirements

The application must store the following entities and relationships:

Entities

User

• Unique identifier
• Email address (unique)
• Name
• Role (Administrator, Coordinator, Driver)
• Approval status (Pending, Approved, Denied)
• Authentication provider identifier
• Profile picture URL (optional)
• Timestamps (created, updated, last login)

VIP

• Unique identifier
• Name
• Organization
• Department (Office of Development, Admin)
• Transport mode (Flight, Self-driving)
• Expected arrival time (for self-driving)
• Airport pickup needed (boolean)
• Venue transportation needed (boolean)
• Notes (text)
• Timestamps (created, updated)

Flight

• Unique identifier
• Linked to VIP
• Flight number
• Flight date
• Segment number (for multi-flight itineraries)
• Departure airport code
• Arrival airport code
• Scheduled departure time
• Scheduled arrival time
• Actual departure time
• Actual arrival time
• Flight status
• Timestamps (created, updated)

Driver

• Unique identifier
• Name
• Phone number
• Department
• Linked to User (optional)
• Timestamps (created, updated)

Schedule Event

• Unique identifier
• Linked to VIP
• Title
• Location
• Start time
• End time
• Description (optional)
• Assigned driver (optional)
• Event type (Transport, Meeting, Event, Meal, Accommodation)
• Status (Scheduled, In-progress, Completed, Cancelled)
• Timestamps (created, updated)

Relationships

• One VIP can have many Flights
• One VIP can have many Schedule Events
• One Driver can be assigned to many Schedule Events
• One User can be linked to one Driver (optional)

---

Success Criteria

Functional Requirements

• ✅ Users can authenticate and remain authenticated
• ✅ All five core features work as specified
• ✅ Role-based permissions are enforced correctly
• ✅ No authentication errors or redirect loops
• ✅ Application runs locally via Docker

Quality Requirements

• ✅ Code is clean and understandable
• ✅ Error messages are clear and helpful
• ✅ User interface is responsive (works on desktop and mobile)
• ✅ Application performs well (feels fast, no noticeable delays)

---

Implementation Notes

• Choose the architecture, patterns, and libraries that make sense for this project
• Focus on simplicity and maintainability
• Avoid over-engineering
• Make it easy to add new features later
• Prioritize getting authentication working reliably first

---

Document Purpose: This document describes what the application must do, not how to build it.
Last Updated: January 24, 2026
Status: Requirements Document