Files
vip-coordinator/docs/USER_GUIDE.md
kyle 74a292ea93 feat: add Help page with search, streamline copilot, misc UI fixes
Adds searchable Help/User Guide page, trims copilot tool bloat,
adds OTHER department option, and various form/layout improvements.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 19:42:39 +01:00

631 lines
25 KiB
Markdown

# VIP Coordinator - User Guide
A comprehensive guide to using the VIP Coordinator application for managing VIP transportation logistics, driver coordination, event scheduling, and fleet management.
---
## Table of Contents
1. [Getting Started](#getting-started)
- [Logging In](#logging-in)
- [Understanding Your Role](#understanding-your-role)
- [Navigation Overview](#navigation-overview)
2. [Dashboard](#dashboard)
3. [War Room (Command Center)](#war-room-command-center)
4. [Managing VIPs](#managing-vips)
- [Viewing the VIP List](#viewing-the-vip-list)
- [Adding a New VIP](#adding-a-new-vip)
- [Editing a VIP](#editing-a-vip)
- [VIP Contact & Emergency Info](#vip-contact--emergency-info)
- [Deleting a VIP](#deleting-a-vip)
5. [Fleet Management](#fleet-management)
- [Drivers Tab](#drivers-tab)
- [Adding a Driver](#adding-a-driver)
- [Vehicles Tab](#vehicles-tab)
- [Adding a Vehicle](#adding-a-vehicle)
6. [Activities (Events & Scheduling)](#activities-events--scheduling)
- [Viewing Activities](#viewing-activities)
- [Creating an Activity](#creating-an-activity)
- [Activity Types](#activity-types)
- [Conflict Detection](#conflict-detection)
7. [Flight Tracking](#flight-tracking)
- [Viewing Flights](#viewing-flights)
- [Adding a Flight](#adding-a-flight)
8. [GPS Tracking](#gps-tracking)
- [Overview](#gps-overview)
- [Enrolling a Driver for GPS](#enrolling-a-driver-for-gps)
- [Live Map](#live-map)
- [GPS Settings](#gps-settings)
9. [Reports](#reports)
- [VIP Accountability Roster](#vip-accountability-roster)
- [PDF Customization](#pdf-customization)
10. [User Management](#user-management)
- [Approving New Users](#approving-new-users)
- [Changing User Roles](#changing-user-roles)
11. [Admin Tools](#admin-tools)
- [Database Statistics](#database-statistics)
- [PDF Customization](#pdf-customization-settings)
- [Signal Messaging](#signal-messaging)
- [Test Data Management](#test-data-management)
12. [AI Assistant](#ai-assistant)
13. [Driver View (My Schedule)](#driver-view-my-schedule)
---
## Getting Started
### Logging In
1. Navigate to your VIP Coordinator URL (e.g., `https://vip.madeamess.online`).
2. Click the **"Sign in with Auth0"** button on the login page.
![Login Page](screenshots/01-login-page.png)
3. You will be redirected to the Auth0 login screen. Enter your email address and password, then click **Continue**.
![Auth0 Login](screenshots/02-auth0-login.png)
4. After successful authentication, you will be redirected to the application.
- **First-time users:** Your account requires administrator approval before you can access the system. You'll see a "Pending Approval" page until an admin approves your account.
- **Returning users:** You'll land on the Dashboard (or My Schedule if you're a Driver).
> **Tip:** Your login session persists across browser refreshes and tabs. You won't need to log in again unless you explicitly sign out or your session expires.
### Understanding Your Role
VIP Coordinator has three user roles, each with different levels of access:
| Feature | Administrator | Coordinator | Driver |
|---------|:---:|:---:|:---:|
| Dashboard & War Room | Full access | Full access | -- |
| VIP Management | Create, Edit, Delete | Create, Edit, Delete | View only |
| Fleet (Drivers/Vehicles) | Create, Edit, Delete | Create, Edit, Delete | View only |
| Activities/Events | Create, Edit, Delete | Create, Edit, Delete | View & Update status |
| Flight Tracking | Full access | Full access | -- |
| GPS Tracking | Full access | Full access | View own location |
| Reports | Full access | Full access | -- |
| User Management | Full access | -- | -- |
| Admin Tools | Full access | -- | -- |
| AI Assistant | Full access | Full access | -- |
### Navigation Overview
The top navigation bar provides access to all major sections:
- **Dashboard** - Quick overview of today's activities and stats
- **War Room** - Real-time command center for active operations
- **VIPs** - Manage VIP profiles and their travel details
- **Fleet** - Manage drivers and vehicles
- **Activities** - Schedule and track events/transport
- **Flights** - Track flight arrivals and departures
- **Admin** (dropdown) - User Management, GPS Tracking, Reports, Admin Tools
Your user avatar and email appear in the top-right corner. Click it to access your profile or sign out.
---
## Dashboard
The Dashboard is your home base, providing a quick overview of the current situation.
![Dashboard](screenshots/03-dashboard.png)
**What you'll see:**
- **Summary Cards** - Quick counts of VIPs, drivers, vehicles, and today's events
- **Today's Schedule** - A timeline of upcoming activities for the day
- **Recent Activity** - Latest changes and updates in the system
- **Quick Actions** - Shortcuts to common tasks like adding a VIP or creating an event
> **Tip:** The Dashboard automatically refreshes to show you the latest data. It's a great page to keep open as your main monitoring screen.
---
## War Room (Command Center)
The War Room is your real-time operations center, designed for active event coordination.
![War Room](screenshots/04-war-room.png)
**Key Features:**
- **Active Events Panel** - Shows all currently in-progress events with live status
- **Upcoming Events** - Events starting soon, sorted by urgency
- **Driver Status** - Which drivers are currently assigned and available
- **Quick Status Updates** - One-click buttons to mark events as started, completed, or cancelled
**How to use the War Room:**
1. Open the **War Room** from the top navigation.
2. Events are color-coded by status:
- **Red/Urgent** - Events starting in the next 5-15 minutes
- **Blue/In Progress** - Currently active events
- **Green/Completed** - Recently finished events
- **Gray/Scheduled** - Upcoming events
3. Click on any event card to see full details or update its status.
4. Use the **Refresh** button to get the latest data instantly.
> **Tip:** The War Room is ideal for day-of-event coordination. Keep it open on a large screen or dedicated monitor during active operations.
---
## Managing VIPs
### Viewing the VIP List
Navigate to **VIPs** from the top menu to see all VIP profiles.
![VIP List](screenshots/05-vip-list.png)
**Features:**
- **Search** - Filter VIPs by name or organization using the search bar
- **Department Filter** - Filter by department (Office of Development, Admin, Other)
- **Arrival Mode** - See whether each VIP is arriving by flight or self-driving
- **Party Size** - Shows the total number of people in the VIP's group
- **Quick Actions** - Edit or view schedule for each VIP
### Adding a New VIP
1. Click the **"+ Add VIP"** button in the top-right corner of the VIP List page.
2. Fill in the VIP's details:
![VIP Edit Form](screenshots/06-vip-edit-form.png)
**Required fields:**
- **Name** - Full name of the VIP
- **Department** - Which department is hosting (Office of Development, Admin, or Other)
- **Arrival Mode** - How the VIP is arriving:
- **Flight** - Arriving by air (enables flight tracking)
- **Self-Driving** - Arriving by personal vehicle (allows setting expected arrival time)
**Optional fields:**
- **Organization** - The VIP's company or organization
- **Airport Pickup** - Check if the VIP needs airport pickup service
- **Venue Transport** - Check if the VIP needs transportation between venues
- **Party Size** - Total number of people (VIP + entourage, default is 1)
- **Notes** - Any special instructions or requirements
- **Roster Only** - Check this if you're only tracking the VIP for accountability purposes (not active coordination)
3. Click **Save** to create the VIP profile.
### Editing a VIP
1. On the VIP List, click the **Edit** (pencil) icon on any VIP row.
2. The edit form opens with the VIP's current information pre-filled.
3. Make your changes and click **Save**.
### VIP Contact & Emergency Info
Scroll down in the VIP edit form to find the contact and emergency information section.
![VIP Contact Info](screenshots/07-vip-edit-contact-info.png)
**Contact fields:**
- **Phone** - VIP's phone number
- **Email** - VIP's email address
- **Emergency Contact Name** - Name of the VIP's emergency contact
- **Emergency Contact Phone** - Phone number for the emergency contact
> **Important:** Emergency contact information is included in the Accountability Roster report. Filling this in is recommended for all VIPs attending large events.
### Deleting a VIP
1. On the VIP List, click the **Delete** (trash) icon on the VIP's row.
2. Confirm the deletion when prompted.
> **Note:** VIP deletion is a "soft delete" - the record is hidden but preserved in the database for audit purposes.
---
## Fleet Management
The Fleet page manages both **Drivers** and **Vehicles** from a single location.
### Drivers Tab
![Fleet - Drivers](screenshots/08-fleet-drivers.png)
The Drivers tab shows all drivers in the system, including:
- **Name** and **Phone** number
- **Department** assignment
- **Availability Status** - Whether the driver is available for assignments
- **Shift Times** - When the driver's shift starts and ends
- **Linked Account** - Whether the driver has a user account for app login
### Adding a Driver
1. Navigate to **Fleet** and ensure the **Drivers** tab is selected.
2. Click the **"+ Add Driver"** button.
3. Fill in the required information:
- **Full Name** (required)
- **Phone Number** (required)
- **Department** (optional - Office of Development, Admin, or Other)
- **User Account ID** (optional - links the driver to a login account)
4. Click **Create Driver**.
> **Tip:** When you link a driver to a user account, that user will be able to log in and see their own schedule on the "My Schedule" page. Create the user account first (they sign up and get approved), then link it here.
### Vehicles Tab
![Fleet - Vehicles](screenshots/09-fleet-vehicles.png)
The Vehicles tab displays your entire fleet, showing:
- **Vehicle Name** - Descriptive name (e.g., "Blue Van", "Suburban #3")
- **Type** - Van, SUV, Sedan, Bus, Golf Cart, or Truck
- **License Plate** number
- **Seat Capacity** - Total available seats
- **Status** - Available, In Use, Maintenance, or Reserved
- **Current Driver** - Who is currently assigned to the vehicle
### Adding a Vehicle
1. Navigate to **Fleet** and click the **Vehicles** tab.
2. Click the **"+ Add Vehicle"** button.
3. Fill in:
- **Vehicle Name** (required) - Give it a recognizable name
- **Type** (required) - Select the vehicle type
- **License Plate** (optional)
- **Seat Capacity** (required) - Total number of passenger seats
- **Notes** (optional) - Any special notes about the vehicle
4. Click **Create Vehicle**.
> **Tip:** Keep vehicle names simple and distinctive. During hectic operations, coordinators need to quickly identify vehicles. Names like "White Suburban" or "Van #2" work well.
---
## Activities (Events & Scheduling)
### Viewing Activities
Navigate to **Activities** from the top menu to see all scheduled events.
![Activities](screenshots/10-activities.png)
**Features:**
- **Status Filters** - Filter by Scheduled, In Progress, Completed, or Cancelled
- **Date Filtering** - View events for specific dates
- **Type Filtering** - Filter by Transport, Meeting, Event, Meal, or Accommodation
- **Search** - Find events by title, VIP name, or location
### Creating an Activity
1. Click **"+ New Activity"** on the Activities page.
2. Fill in the event details:
- **Title** (required) - Descriptive name for the event
- **Type** - Transport, Meeting, Event, Meal, or Accommodation
- **VIP(s)** - Select one or more VIPs for this event
- **Start Time** and **End Time** (required)
- **Driver** (optional) - Assign a driver
- **Vehicle** (optional) - Assign a vehicle
- **Pickup Location** and **Dropoff Location** (for transport events)
- **Location** (for non-transport events)
- **Description** and **Notes** (optional)
3. Click **Create** to save the event.
### Activity Types
| Type | Use For |
|------|---------|
| **Transport** | Airport pickups, venue-to-venue rides, departure drops |
| **Meeting** | Scheduled meetings between VIPs and hosts |
| **Event** | Conferences, ceremonies, tours, and other events |
| **Meal** | Breakfast, lunch, dinner, and receptions |
| **Accommodation** | Hotel check-in/check-out |
### Conflict Detection
When creating or editing an activity, the system automatically checks for scheduling conflicts:
- **Driver conflicts** - A driver can't be assigned to two events at the same time
- **Vehicle conflicts** - A vehicle can't be double-booked
- **VIP conflicts** - VIPs can't be in two places at once
If a conflict is detected, you'll see a warning with details about the overlapping event. You can choose to proceed anyway or adjust the timing.
---
## Flight Tracking
### Viewing Flights
Navigate to **Flights** from the top menu to see all tracked flights.
![Flights](screenshots/11-flights.png)
**The flights page shows:**
- **Flight Number** - Airline and flight number (e.g., AA1234)
- **Route** - Departure and arrival airports (IATA codes)
- **Date** - Flight date
- **Scheduled Times** - Planned departure and arrival
- **Actual Times** - Real departure and arrival (when available)
- **Status** - Scheduled, Delayed, In Air, Landed, etc.
- **VIP** - Which VIP is on this flight
### Adding a Flight
Flights are typically added through the VIP edit form:
1. Navigate to a VIP's profile (edit the VIP).
2. In the **Flights** section, click **"+ Add Flight"**.
3. Enter:
- **Flight Number** (e.g., "AA1234")
- **Flight Date**
- **Departure Airport** (IATA code, e.g., "JFK")
- **Arrival Airport** (IATA code, e.g., "LAX")
- **Segment** - For multi-leg itineraries (1 for first leg, 2 for second, etc.)
4. The system will attempt to look up real-time flight data if an API key is configured.
> **Tip:** Use standard IATA 3-letter airport codes (e.g., JFK, LAX, ORD, ATL). The system uses these to track flight status automatically.
---
## GPS Tracking
### GPS Overview
The GPS Tracking page provides real-time location monitoring for your driver fleet.
![GPS Tracking](screenshots/15-gps-tracking.png)
**Dashboard cards at the top show:**
- **Total Enrolled** - Number of drivers enrolled in GPS tracking
- **Active Now** - Drivers currently reporting their location
- **Update Interval** - How frequently locations update (e.g., 30 seconds)
- **Shift Hours** - Hours during which tracking is active
The page has four tabs: **Live Map**, **Devices**, **Stats**, and **Settings**.
### Enrolling a Driver for GPS
To enable GPS tracking for a driver, you need to enroll them:
![GPS Devices](screenshots/16-gps-devices.png)
1. Go to **GPS Tracking** and click the **Devices** tab.
2. Click the **"Enroll Driver"** button.
3. Select the driver you want to enroll from the dropdown.
4. The system will create a unique device identifier for that driver.
5. The driver then needs to install the **Traccar Client** app on their phone:
- Available for both **iOS** (App Store) and **Android** (Google Play)
- Search for "Traccar Client" in the app store
6. In the Traccar Client app, configure:
- **Device identifier** - Enter the unique ID shown after enrollment
- **Server URL** - Enter the Traccar server URL provided by your administrator
- **Frequency** - Set to match your GPS settings (e.g., 30 seconds)
- **Location accuracy** - Set to "High"
7. Enable tracking in the app and the driver's location will appear on the Live Map.
> **Important:** GPS tracking respects driver privacy. Tracking only occurs during configured shift hours. Drivers must give consent, and the system clearly shows when tracking is active.
### Live Map
The **Live Map** tab shows all active drivers on an interactive map:
- **Green dots** indicate active drivers currently reporting location
- **Gray dots** indicate enrolled but inactive drivers
- Click on any driver marker to see their name, speed, and last update time
- The map auto-refreshes based on the configured update interval
### GPS Settings
![GPS Settings](screenshots/17-gps-settings.png)
Administrators can configure GPS tracking behavior:
1. Go to **GPS Tracking** and click the **Settings** tab.
2. Adjustable settings:
- **Update Interval** (30-300 seconds) - How often driver phones report location. Lower values = more precise tracking but higher battery usage.
- **Data Retention** (7-90 days) - How long location history is kept before automatic cleanup.
- **Tracking Hours** - Set the start and end time for when GPS tracking is active. Drivers are NOT tracked outside these hours.
3. Click **Save** to apply changes.
> **Tip:** For most events, a 30-60 second update interval provides good tracking while preserving driver phone battery. During critical operations, you can temporarily lower this to 15-30 seconds.
---
## Reports
### VIP Accountability Roster
Navigate to **Reports** under the **Admin** dropdown to access the accountability roster.
![Reports](screenshots/12-reports.png)
The **VIP Accountability Roster** is a comprehensive report designed for event-day accountability. It includes:
- **VIP Name and Organization**
- **Contact Information** (phone, email)
- **Emergency Contact** details
- **Arrival Mode** and expected arrival time
- **Assigned Driver and Vehicle**
- **Flight Details** (for VIPs arriving by air)
- **Party Size**
- **Special Notes**
**To generate the report:**
1. Navigate to **Reports**.
2. The roster is displayed on screen with all active VIPs.
3. Click **"Download PDF"** to generate a professionally formatted PDF document.
4. The PDF uses your configured branding (logo, colors, contact info) from the Admin Tools settings.
> **Tip:** Print the Accountability Roster before each event starts. It serves as a backup reference when technology isn't available and is useful for emergency situations where you need quick access to VIP contact and emergency information.
### PDF Customization
The appearance of generated PDF reports can be fully customized. See [Admin Tools > PDF Customization](#pdf-customization-settings) for details.
---
## User Management
Administrators can manage user accounts from the **Users** page.
![User Management](screenshots/13-users.png)
### Approving New Users
When a new person signs up, their account starts in a "Pending Approval" state:
1. Navigate to **Admin > Users**.
2. Look for users with a **"Pending"** status badge.
3. Click **"Approve"** to grant them access to the system.
4. The user will be able to log in on their next attempt.
> **Note:** The very first user to register is automatically approved and given the Administrator role. All subsequent users require manual approval.
### Changing User Roles
1. On the Users page, find the user whose role you want to change.
2. Use the **Role** dropdown to select:
- **Administrator** - Full system access, can manage users and settings
- **Coordinator** - Can manage VIPs, drivers, events, and view all data
- **Driver** - Limited view, can see their own schedule and update event status
3. The change takes effect immediately.
> **Warning:** Be careful when changing roles. Removing someone's Administrator role cannot be undone by that user - another admin must restore it.
---
## Admin Tools
The Admin Tools page is only accessible to Administrators and provides system management capabilities.
![Admin Tools](screenshots/14-admin-tools.png)
### Database Statistics
At the top of the page, you'll see a live count of all records in the system:
- Number of VIPs, Drivers, Vehicles, Events, Flights, and Users
- Click **Refresh** to update the counts
### PDF Customization Settings
Customize how generated PDF documents look:
**Branding:**
- **Organization Name** - Appears in the PDF header
- **Organization Logo** - Upload your logo (PNG, JPG, or SVG, max 2MB)
- **Accent Color** - The primary color used for headers and section titles
- **Tagline** - Optional text below the organization name
**Contact Information:**
- **Contact Email** and **Phone** - Shown in the PDF footer
- **Secondary Contact** - Optional backup contact
- **Contact Label** - The heading above contact info (e.g., "Questions or Changes?")
**Document Options:**
- **Draft Watermark** - Add a diagonal "DRAFT" watermark
- **Confidential Watermark** - Add a "CONFIDENTIAL" watermark
- **Show Timestamp** - Include generation date/time
- **Page Size** - Letter or A4
**Content Display:**
- Toggle visibility of flight info, driver names, vehicle names, VIP notes, and event descriptions
**Custom Messages:**
- **Header Message** - Custom text at the top of the document
- **Footer Message** - Custom text at the bottom
Click **"Preview Sample PDF"** to see how your settings look before saving, then click **"Save PDF Settings"** to apply.
### Signal Messaging
The Signal Messaging section allows you to communicate with drivers via Signal (encrypted messaging):
- **Connection Status** - Shows whether the Signal service is connected and which phone number is linked
- **Send Test Message** - Send a test message to verify the connection
- **Chat History** - View message statistics and manage chat history
### Test Data Management
For development and demo purposes:
- **Generate Complete Test Data** - Creates a full set of realistic test data (20 VIPs, 8 drivers, 10 vehicles, 100+ events)
- **Refresh Event Times** - Keeps existing VIPs/drivers/vehicles but regenerates all events with fresh timestamps relative to the current time
- **Clear All Data** - Removes all VIPs, drivers, vehicles, events, flights, and messages
> **Warning:** "Clear All Data" is irreversible. Only use it when you want to start completely fresh.
---
## AI Assistant
The AI Assistant is a built-in copilot that can help you with VIP coordination tasks.
![AI Assistant](screenshots/18-ai-assistant.png)
**To open the AI Assistant:**
1. Click the blue **"AI Assistant"** button in the bottom-right corner of any page.
2. The chat panel slides open.
**What the AI Assistant can do:**
- Answer questions about your VIPs, drivers, and events
- Look up what's happening today or at specific times
- Find available drivers for assignments
- Check which VIPs are arriving by flight
- Help you understand the current status of operations
- Process screenshots of emails (upload an image of an email with VIP travel details)
**Example questions you can ask:**
- *"What's happening today?"*
- *"Who are the VIPs arriving by flight?"*
- *"Which drivers are available right now?"*
- *"Show me the schedule for Roger Mosby"*
- *"What events are in progress?"*
**To upload an image:**
1. Click the **image upload** button (camera icon) in the chat input area.
2. Select a screenshot or photo (e.g., an email with travel itinerary details).
3. The AI will read the image and extract relevant information.
> **Tip:** The AI Assistant has access to your live data. It can query VIPs, drivers, events, and more in real-time. Use it as a quick way to get answers without navigating to different pages.
---
## Driver View (My Schedule)
Drivers who have a linked user account see a simplified interface focused on their assignments.
**When a driver logs in, they see:**
- **My Schedule** - Their personal schedule showing only events assigned to them
- **Today's Events** - Quick view of what's coming up
- **Status Updates** - Ability to mark their events as "In Progress" or "Completed"
**How drivers update event status:**
1. On their schedule, find the current event.
2. Click the status button to cycle through:
- **Scheduled** (default) - Not yet started
- **In Progress** - Currently underway (click when you start the pickup/transport)
- **Completed** - Finished (click when the VIP has been dropped off)
3. Coordinators and administrators see these status changes in real-time on the War Room.
> **Tip for Drivers:** Keep your event statuses updated! This helps the coordination team know exactly where VIPs are at all times. Mark "In Progress" when you begin a pickup and "Completed" when the VIP is delivered to their destination.
---
## Frequently Asked Questions
**Q: I just signed up but can't access anything. What do I do?**
A: Your account needs to be approved by an administrator. Contact your team lead and ask them to approve your account in the User Management section.
**Q: I'm a driver but I can't see my schedule. What's wrong?**
A: Make sure your user account is linked to a driver profile. An administrator needs to go to Fleet > Drivers, find your driver record, and enter your User Account ID.
**Q: Can I use the app on my phone?**
A: Yes! The web application is responsive and works on mobile browsers. Simply navigate to the same URL on your phone's browser. For GPS tracking, you'll also need the Traccar Client app.
**Q: How do I change my password?**
A: Passwords are managed through Auth0. Click your profile avatar in the top-right corner, then follow the "Change Password" link, or use the "Forgot Password" option on the login screen.
**Q: What happens if two events conflict?**
A: The system will warn you about scheduling conflicts when creating or editing events. You'll see which driver, vehicle, or VIP has an overlapping booking and can choose to adjust the timing or proceed anyway.
**Q: Is the GPS tracking always on?**
A: No. GPS tracking only operates during the configured Shift Hours (set by administrators). Outside those hours, driver locations are not tracked or recorded.
**Q: How long is location data kept?**
A: Location data is automatically deleted after the configured retention period (default: 30 days). Administrators can adjust this in GPS Settings.
---
*This documentation was generated for VIP Coordinator. For technical support or feature requests, contact your system administrator.*