Turnpike/docs/USAGE.md

# Turnpike Usage Guide

This guide is for event organizers and ops teams running a Turnpike instance. For installation and deployment, see [INSTALLATION.md](INSTALLATION.md).

## First Login

On first startup with `TURNPIKE_ADMIN_USER` and `TURNPIKE_ADMIN_PASSWORD` set, Turnpike creates a bootstrap admin account. Log in at `https://your-instance/` with those credentials.

After logging in, create accounts for your team under **Users**. Each user gets a username, password, and role. The admin bootstrap credentials are only used on initial setup — they have no effect on subsequent restarts.

## User Roles

| Role | What they see | What they can do |
|------|--------------|------------------|
| **admin** | All pages + Settings | Everything: attendee import, user management, SMTP config, departments, shifts, volunteers |
| **coordinator** | Dashboard, Schedule Board, Volunteers, Departments, Shifts | Manage volunteers, departments, and shifts across all departments. Cannot manage users or settings |
| **volunteer_lead** | Schedule Board, Volunteers, Departments | Manage volunteers and shifts within their assigned department only |
| **gate** | Full-screen Gate UI | Check in attendees (search + QR scan). No access to other pages |

Ticketing and ops staff should use the **admin** role. The `ticketing` role exists in the codebase but is effectively unused — admin covers all ticketing functions.

Volunteer leads are scoped to a single department. When creating a volunteer_lead user, assign their department.

## Event Setup

1. **Configure your event** — go to the Dashboard and set the event name and dates.
2. **Create departments** — under Departments, add each department your event needs (e.g., Gate, Greeters, Rangers, Build, LNT).
3. **Import attendees** — see next section.
4. **Create shifts** — under Shifts, create shifts for each department with day, start/end time, and capacity.

## Importing Attendees

Go to **Import** and upload a CSV file. Turnpike auto-detects two formats:

### CrowdWork / Zeffy format

| Column | Maps to |
|--------|---------|
| `Patron Name` | Name |
| `Patron Email` | Email |
| `Order Number` | Ticket ID |
| `Tier Name` | Ticket type |

### Generic format

| Column | Maps to |
|--------|---------|
| `name` (required) | Name |
| `email` | Email |
| `ticket_id` | Ticket ID |
| `ticket_type` | Ticket type |
| `note` | Note |

Column matching is case-insensitive. Extra columns are ignored. BOM-encoded files (Windows Excel exports) are handled automatically.

### Party-size dedup

CrowdWork exports one row per ticket, even when the same person bought multiple tickets in one order. Turnpike handles this automatically:

- First row for "Titania Fairweather" (order 1234) creates a record with `party_size=1`
- Subsequent rows with the same name + order number increment `party_size` (no duplicate record)
- Result: one attendee record, `party_size=3` if three tickets were purchased

The import result shows `inserted` (new records), `grouped` (merged into existing party), and `skipped` (exact duplicates).

Re-importing the same CSV is safe — existing records are skipped, not duplicated.

## Managing Volunteers

Under **Volunteers**, you can:

- Create volunteers manually (name, email, department)
- Link a volunteer to an existing attendee record (for dual check-in at the gate)
- Assign volunteers to departments
- Check in volunteers

Volunteers are separate from attendees. A person can be both an attendee (ticket holder) and a volunteer (shift worker). Linking them enables the gate team to check in both records simultaneously.

## Shift Scheduling

Under **Shifts**, create shifts for each department:

- **Day** — the date of the shift
- **Start/end time** — HH:MM format
- **Capacity** — maximum number of volunteers

### Assigning volunteers

From the Shifts page or the Schedule Board, assign volunteers to shifts. Turnpike checks for conflicts — if a volunteer already has a shift on the same day with overlapping times, you'll see a warning and can choose to force the assignment.

### Reordering

Shifts can be reordered within a department to reflect priority or sequence. The Schedule Board supports drag-and-drop reordering.

## Volunteer Kiosk

The kiosk lets volunteers self-select shifts without logging in.

### Setup

1. **Generate tokens** — on the Attendees page, click "Generate Tokens." This creates a unique 8-character code for every attendee that doesn't have one.
2. **Distribute tokens** — two options:
   - **Export CSV** — downloads a file with columns `Email Address`, `First Name`, `Token`, `Signup Link`. Import this into MailChimp, Zeffy, or any email platform.
   - **Email directly** — if SMTP is configured (see below), use "Email All" to send token links, or email individually per attendee.
3. **Set base URL** — in Settings, set the public base URL (e.g., `https://turnpike.example.com`). Token links use this URL.

### Volunteer experience

Each volunteer receives a link like `https://turnpike.example.com/#/v/ABC12345`. This opens a mobile-friendly page showing:

- Their name and department
- Currently assigned shifts
- Available shifts with remaining capacity

Claiming a shift checks for time conflicts. If a conflict exists, the volunteer sees which shifts overlap and can confirm to proceed anyway.

No login is required. The 8-character token authenticates the request.

### Token format

Tokens use the character set `A-Z, 2-9` (excluding 0/O, 1/I/L to avoid ambiguity when reading aloud or on printed badges).

## Gate Check-In

Users with the **gate** role see a dedicated full-screen UI:

- **QR scanner** — uses the device camera via the BarcodeDetector API. Scanned codes populate the search field.
- **Search** — type a name to filter attendees in real-time (searches local IndexedDB, works offline).
- **Party check-in** — for attendees with `party_size > 1`, the gate UI shows progress ("2/3 checked in") and offers "Check in 1" or "Check in all remaining."
- **Volunteer dual check-in** — if an attendee is linked to a volunteer record, the gate UI shows their volunteer status and offers to check in both simultaneously.
- **Recent check-ins** — the last 10 check-ins are shown for quick reference.

Gate devices should install Turnpike as a PWA (Add to Home Screen) for the best experience. Check-ins are stored locally and sync when connectivity is available.

## Schedule Board

The Schedule Board is the primary UI for coordinators and volunteer leads. It shows:

- Shifts grouped by department and day
- Each shift card shows: name, time, capacity (used/total), assigned volunteers
- Conflict badges when a volunteer has overlapping shifts on the same day

**Coordinators and admins** see all departments. **Volunteer leads** see only their assigned department.

Actions available:
- Assign volunteers to shifts from a dropdown
- Remove volunteer assignments
- Reorder shifts within a department
- Edit shift details inline

## SMTP Configuration

SMTP enables token email distribution and test emails. Configure in **Settings** (admin only):

| Field | Description |
|-------|-------------|
| SMTP Host | Mail server hostname (e.g., `smtp.fastmail.com`) |
| SMTP Port | `587` for STARTTLS (default), `465` for implicit TLS |
| SMTP User | Login username |
| SMTP Password | Login password |
| From Address | Sender email address |
| From Name | Sender display name |

After saving, use "Send Test Email" to verify the configuration.

SMTP can also be set via CLI flags (`--smtp-host`, etc.) which override database values.

## Offline Mode

Turnpike is a Progressive Web App (PWA). After the first load, it works offline:

- **Gate check-ins** are stored in the browser's IndexedDB and sync when connectivity returns.
- **Real-time updates** use Server-Sent Events (SSE). When the connection drops, the client reconnects automatically.
- **Sync** pulls all changes from the server on startup and periodically thereafter. Local changes are queued in an outbox and flushed in order.

Install Turnpike as a PWA (Add to Home Screen on mobile, or Install App in desktop Chrome) for the best offline experience.

## CSV Exports

Two CSV exports are available from the Attendees page:

- **Attendee export** — all attendee records with check-in status
- **Token link export** — columns: `Email Address`, `First Name`, `Token`, `Signup Link`. Only includes attendees with tokens. Compatible with MailChimp and Zeffy for bulk email campaigns.