pen/Turnpike
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated docs.

Browse source
This commit is contained in:
Pen Anderson 2026-03-04 23:02:35 -06:00
parent 6eb72c5091
commit a60ef7d25b
3 changed files with 66 additions and 67 deletions
Download patch file Download diff file Expand all files Collapse all files

86
docs/USAGE.md
View file

@ -12,23 +12,22 @@ After logging in, create accounts for your team under **Users**. Each user gets
| 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 |
| **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 |
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.
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 the Dashboard and set the event name and dates.
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 attendees** — see next section.
3. **Import participants** — see next section.
4. **Create shifts** — under Schedule, create shifts for each department with day, start/end time, and capacity.
## Importing Attendees
## Importing Participants
Go to **Import** and upload a CSV file. Turnpike auto-detects two formats:
@ -36,7 +35,7 @@ Go to **Import** and upload a CSV file. Turnpike auto-detects two formats:
| Column | Maps to |
|--------|---------|
| `Patron Name` | Name |
| `Patron Name` | Ticket name |
| `Patron Email` | Email |
| `Order Number` | Ticket ID |
| `Tier Name` | Ticket type |
@ -45,7 +44,7 @@ Go to **Import** and upload a CSV file. Turnpike auto-detects two formats:
| Column | Maps to |
|--------|---------|
| `name` (required) | Name |
| `name` (required) | Ticket name |
| `email` | Email |
| `ticket_id` | Ticket ID |
| `ticket_type` | Ticket type |
@ -53,27 +52,21 @@ Go to **Import** and upload a CSV file. Turnpike auto-detects two formats:
Column matching is case-insensitive. Extra columns are ignored. BOM-encoded files (Windows Excel exports) are handled automatically.
### Party-size dedup
### Participants and tickets
CrowdWork exports one row per ticket, even when the same person bought multiple tickets in one order. Turnpike handles this automatically:
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).
- 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.
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.
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}`).
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.
@ -90,7 +83,7 @@ In **Settings**, the "Volunteer Signup" card controls:
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.
- **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.
@ -100,11 +93,11 @@ If a volunteer confirms their email while signups are already open, they receive
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
- Mark volunteers as co-leads
- 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.
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
@ -128,15 +121,17 @@ 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.
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:
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
@ -144,20 +139,19 @@ Each volunteer receives a link like `https://turnpike.example.com/#/v/ABC12345`.
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.
No login is required. The kiosk code authenticates the request.
### Token format
### Code 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).
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 **gate** role see a dedicated full-screen UI:
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 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.
- **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.
@ -170,7 +164,7 @@ The Schedule page is the primary UI for managing shifts and volunteer assignment
- 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.
**Admins and staffing** see all departments. **Coleads** see only their assigned department(s).
Actions available:
- Create new shifts (+ Add shift button)
@ -182,7 +176,7 @@ Actions available:
## SMTP Configuration
SMTP enables token email distribution and test emails. Configure in **Settings** (admin only):
SMTP enables volunteer confirmation emails, kiosk link distribution, and test emails. Configure in **Settings** (admin only):
| Field | Description |
|-------|-------------|
@ -203,13 +197,13 @@ 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.
- **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
Two CSV exports are available from the Attendees page:
CSV exports are available from the Participants 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.
- **Participant export** — all participant records with check-in status
- **Ticket export** — all ticket records with codes and check-in status