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: participant import, user management, SMTP config, departments, shifts, volunteers |
| **ticketing** | Participants, Tickets, Import | Manage participants and tickets, run CSV imports |
| **staffing** | Dashboard, Schedule, Volunteers, Departments | Manage volunteers, departments, and shifts across all departments. No user management or settings |
| **colead** | Dashboard, Schedule, Volunteers | Manage volunteers and shifts within their assigned department(s) only |
| **gatekeeper** | Full-screen Gate UI | Check in ticket holders (search + QR scan). No access to other pages |

Coleads are scoped to one or more departments. When creating a colead user, assign their department(s).

## Event Setup

1. **Configure your event** — set the event name, venue, dates, and timezone via the API (`PUT /api/event`). These appear on the Dashboard.
2. **Create departments** — under Departments, add each department your event needs (e.g., Gate, Greeters, Rangers, Build, LNT).
3. **Import participants** — see next section.
4. **Create shifts** — under Schedule, create shifts for each department with day, start/end time, and capacity.

## Importing Participants

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

### CrowdWork / Zeffy format

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

### Generic format

| Column | Maps to |
|--------|---------|
| `name` (required) | Ticket 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.

### Participants and tickets

Each row in the CSV creates one **ticket**. Participants are deduplicated by email — multiple tickets with the same email address are linked to a single participant record. The import result shows `inserted` (new tickets) and `skipped` (exact duplicates).

Re-importing the same CSV is safe — exact duplicates are skipped, not duplicated.

## Volunteer Signup

Turnpike provides a public signup form for volunteers at `/volunteer-signup`. No login is required.

### Signup flow

1. Volunteer visits the signup form and fills in: preferred name (required), ticket name, email (required), pronouns, phone, department preference, and an optional note.
2. Turnpike creates a volunteer record and auto-links it to an existing participant by email match, or creates a new participant record.
3. A confirmation email is sent with a unique link (`/confirm/{token}`).
4. The volunteer clicks the link to confirm their email.
5. If shift signups are already open, the confirmation page includes a link to the kiosk for shift selection.

Duplicate signups with the same email silently succeed — no error is shown and no duplicate is created. This prevents email enumeration.

### Configuring the signup form

In **Settings**, the "Volunteer Signup" card controls:

- **Note field label** — customize the label shown on the form (default: "Additional note")
- **Note field required** — when checked, volunteers must fill in the note to submit

### Opening shift signups

In **Settings**, the "Shift Signups" card has an open/close toggle:

- **Opening** signups generates kiosk codes for all confirmed volunteers and emails them their shift signup links. A confirmation dialog warns before sending.
- **Closing** signups prevents new kiosk links from being issued on confirmation, but existing links continue to work.

If a volunteer confirms their email while signups are already open, they receive their kiosk link immediately in the confirmation response and via email.

## Managing Volunteers

Under **Volunteers**, you can:

- Create volunteers manually (name, email, department)
- Assign volunteers to departments
- Mark volunteers as co-leads
- Check in volunteers

Volunteers are separate from participants. A person can be both a ticket holder and a volunteer. When a volunteer signs up via the public form, they are automatically linked to their participant record by email.

## Shift Scheduling

Under **Schedule**, 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 Schedule page, 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 using the up/down buttons on each shift card.

## Volunteer Kiosk

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

### Setup

Kiosk links are generated and distributed automatically through the volunteer signup flow:

1. Volunteers sign up via the public signup form (`/volunteer-signup`) and confirm their email.
2. In **Settings**, open shift signups. This generates kiosk codes for all confirmed volunteers and emails them their links. A confirmation dialog warns before sending.
3. If a volunteer confirms their email while signups are already open, they receive their kiosk link immediately.

**Set base URL** — in Settings, set the public base URL (e.g., `https://turnpike.example.com`). Kiosk 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 kiosk code authenticates the request.

### Code format

Kiosk codes 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 **gatekeeper** 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 tickets in real-time (searches local IndexedDB, works offline).
- **Volunteer dual check-in** — if a ticket holder is also a volunteer, 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

The Schedule page is the primary UI for managing shifts and volunteer assignments. 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

**Admins and staffing** see all departments. **Coleads** see only their assigned department(s).

Actions available:
- Create new shifts (+ Add shift button)
- Edit shift details inline
- Delete shifts
- Assign volunteers to shifts from a dropdown
- Remove volunteer assignments
- Reorder shifts within a department

## SMTP Configuration

SMTP enables volunteer confirmation emails, kiosk link 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.

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

## CSV Exports

CSV exports are available from the Participants page:

- **Participant export** — all participant records with check-in status
- **Ticket export** — all ticket records with codes and check-in status