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.

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, Volunteers, Departments	Manage volunteers, departments, and shifts across all departments. Cannot manage users or settings
volunteer_lead	Schedule, 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 Schedule, 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.

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 attendee by email match, or creates a new attendee 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 tokens 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)
• 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 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

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

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

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

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 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.