Turnpike/README.md

# Turnpike

Self-hosted event attendee and volunteer management. One instance, one event.

Turnpike handles gate check-in, volunteer scheduling, and department coordination for events ranging from a single evening to a multi-day festival. It works offline — gate volunteers can check people in without a network connection and sync when connectivity returns.

## Features

- **Attendee management** — CSV import (CrowdWork/Zeffy auto-detected), party-size tracking, search, check-in
- **Volunteer scheduling** — departments, shifts with capacity, conflict detection, reordering
- **Public volunteer signup** — self-registration form with email confirmation, auto-attendee linking
- **Volunteer kiosk** — token-authenticated self-service shift signup, no login required
- **Gate check-in** — full-screen UI with QR scanner, party check-in ("2/3 checked in"), volunteer dual check-in
- **Schedule** — create shifts, assign volunteers, manage assignments with conflict awareness
- **Role-based access** — admin, coordinator, volunteer lead (department-scoped), gate
- **Offline-first PWA** — installs on phones/tablets, full offline check-in with background sync
- **Real-time** — check-ins and changes broadcast live via SSE
- **SMTP email** — send volunteer token links directly or export CSV for bulk email platforms
- **Single binary** — Go backend embeds the frontend; no runtime dependencies

## Tech Stack

- **Backend:** Go, SQLite (WAL mode), JWT auth
- **Frontend:** Svelte 5, Dexie (IndexedDB), Vite
- **Deployment:** single static binary — no CGO, no external database

## Quick Start

```sh
# Build (frontend + Go binary)
make build

# Run (creates admin user on first startup)
TURNPIKE_ADMIN_USER=admin TURNPIKE_ADMIN_PASSWORD=changeme ./turnpike
```

Open `http://localhost:8180`.

See [docs/INSTALLATION.md](docs/INSTALLATION.md) for systemd, Docker, NixOS, and reverse proxy setup.

## Configuration

| Flag | Env var | Default | Description |
|------|---------|---------|-------------|
| `--addr` | — | `0.0.0.0:8180` | Listen address |
| `--db` | — | `turnpike.db` | SQLite database path |
| `--secret` | `TURNPIKE_SECRET` | auto-generated | JWT signing secret (persist across restarts) |
| `--token-expiry` | — | `24` | JWT lifetime in hours |
| `--base-url` | — | — | Public URL for volunteer token links |
| `--smtp-host` | — | — | SMTP server hostname |
| `--smtp-port` | — | `587` | SMTP port (587 = STARTTLS, 465 = implicit TLS) |
| `--smtp-user` | — | — | SMTP username |
| `--smtp-password` | — | — | SMTP password |
| `--smtp-from` | — | — | Sender email address |
| `--smtp-from-name` | — | — | Sender display name |
| — | `TURNPIKE_ADMIN_USER` | — | Bootstrap admin username (first run only) |
| — | `TURNPIKE_ADMIN_PASSWORD` | — | Bootstrap admin password (first run only) |

## User Roles

| Role | Access |
|------|--------|
| `admin` | Full access: attendee import, user management, SMTP settings, all departments and shifts |
| `coordinator` | All departments: volunteers, shifts, schedule. No user management or settings |
| `volunteer_lead` | Own department only: volunteers and shifts scoped to assigned department |
| `gate` | Full-screen check-in UI with QR scanner. No access to other pages |

See [docs/USAGE.md](docs/USAGE.md) for detailed workflow documentation.

## Development

**Prerequisites:** [Nix](https://nixos.org) + [direnv](https://direnv.net), or Go 1.24+ and Node.js 18+ installed manually.

```sh
git clone <repo-url>
cd turnpike
direnv allow   # activates Go + Node.js via flake.nix
```

**Two-terminal dev setup:**

```sh
# Terminal 1 — Go API server
go run . --db dev.db

# Terminal 2 — Vite dev server (proxies /api to :8180)
cd frontend && npm install && npm run dev
```

The Vite dev server runs on `:5173` and proxies `/api` requests to the Go server on `:8180`.

## Documentation

- [Usage Guide](docs/USAGE.md) — event setup, attendee import, volunteer signup, volunteer kiosk, gate check-in, schedule
- [Installation Guide](docs/INSTALLATION.md) — building, deploying, systemd, Docker, NixOS, reverse proxy, backup

## License

CC BY-NC-SA 4.0