docs: Organize documentation into structured folders
Some checks failed
CI/CD Pipeline / Backend Tests (push) Has been cancelled
CI/CD Pipeline / Frontend Tests (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (push) Has been cancelled
CI/CD Pipeline / Security Scan (push) Has been cancelled
CI/CD Pipeline / Deploy to Staging (push) Has been cancelled
CI/CD Pipeline / Deploy to Production (push) Has been cancelled
Some checks failed
CI/CD Pipeline / Backend Tests (push) Has been cancelled
CI/CD Pipeline / Frontend Tests (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (push) Has been cancelled
CI/CD Pipeline / Security Scan (push) Has been cancelled
CI/CD Pipeline / Deploy to Staging (push) Has been cancelled
CI/CD Pipeline / Deploy to Production (push) Has been cancelled
Organized documentation into cleaner structure: Root directory (user-facing): - README.md - Main documentation - CLAUDE.md - AI context (referenced by system) - QUICKSTART.md - Quick start guide docs/ (technical documentation): - CASL_AUTHORIZATION.md - Authorization guide - ERROR_HANDLING.md - Error handling patterns - REQUIREMENTS.md - Project requirements docs/deployment/ (production deployment): - HTTPS_SETUP.md - SSL/TLS setup - PRODUCTION_ENVIRONMENT_TEMPLATE.md - Env vars template - PRODUCTION_VERIFICATION_CHECKLIST.md - Deployment checklist Removed: - DOCKER_TROUBLESHOOTING.md - Outdated (referenced Google OAuth, old domain) Updated references: - Fixed links to moved files in CASL_AUTHORIZATION.md - Fixed links to moved files in ERROR_HANDLING.md - Removed reference to deleted BUILD_STATUS.md in QUICKSTART.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
282
docs/REQUIREMENTS.md
Normal file
282
docs/REQUIREMENTS.md
Normal file
@@ -0,0 +1,282 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user