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