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: 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 Kiosk	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 — go to Settings and set the event name, venue, dates, and timezone. These appear on the Dashboard and volunteer signup page.
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 registered (email-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, co-lead, note)
• Edit existing volunteers (department, co-lead, note) via the inline Edit button
• Confirm registered volunteers (admin, staffing, colead)
• Mark volunteers as ready (briefed at the volunteer station)

Volunteer statuses

Status	Meaning	Who sets it
Unconfirmed	Signed up but hasn't confirmed their email	Automatic (not yet done)
Registered	Email confirmed — volunteer is in the system	Automatic (email link)
Confirmed	Staff has verified the volunteer is assigned and ready to be scheduled	Admin, staffing, or co-lead
Ready	Briefed at the volunteer station, cleared to report for shifts	Gate staff at check-in

Confirmation is a deliberate staff action — it signals that you're expecting the volunteer for shifts. Use the Confirm button on a registered volunteer's row. Marking a volunteer as a co-lead (is_lead) automatically confirms them.

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 Volunteer Kiosk is the public-facing flow for volunteers: signup, email confirmation, and shift self-scheduling. The shift scheduling page 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 registered (email-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 Kiosk

Users with the gatekeeper role see a dedicated full-screen Gate Kiosk:

• 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).
• Recent check-ins — the last 10 check-ins are shown for quick reference.

Admins and ticketing leads can also check in tickets directly from the Participants page by expanding a participant's tickets.

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