game-scoreboard/docs/PRD.md

# PRD — Game Night Live

## 1. Goal
Run a youth game night (e.g. "Worship Game Night") from one admin tab while a projector tab shows a
live scoreboard, and judges score from their phones via links. Versatile enough for any game format.

## 2. Roles
| Role | Access | How they get in |
|---|---|---|
| **Admin** | Everything | Logs in (magic link). Email must be in `ADMIN_EMAILS`. |
| **Scoreboard viewer** | Read-only scoreboard for ONE event | Public link `/s/{scoreboardToken}` |
| **Judge** | Score ONE game | Personal link `/j/{judgeToken}` OR open game link `/jo/{openToken}` (enters name first) |

## 3. Core concepts
- **Event** — one game night. Has teams, games, one scoreboard link, visibility state.
- **Team** — name + colour. Belongs to an event.
- **Game** — one activity. Ordered. Has a scoring mode:
  - `judged` — judges submit scores via links; admin can see progress & override.
  - `direct` — admin enters scores directly.
- **Criterion ("block")** — one thing being scored in a game. A game has 1..N criteria.
  - e.g. Karaoke: Pitch, Energy, Lyrics accuracy, Stage presence, Crowd reaction (each 1–5).
  - e.g. Guess the Lyric: one criterion "Correct answers" (number input, 0–20).
  - Input type: `blocks` (tap a number in a row of buttons) or `number` (free numeric input / +/- stepper).
  - Has min, max, step, weight, and a description (shown to whoever scores it).
- **Points mode** per game (how a game's result becomes leaderboard points):
  - `raw` — game points = criteria total × multiplier.
  - `placement` — teams ranked by criteria total, then awarded placement points (default 10/7/5/3).
- **Adjustment** — bonus or penalty points with a reason, optionally tied to a game.
- **Notes** — `admin_notes` (only admin sees) and `judge_notes` (judges see) per game.

## 4. Features

### 4.1 Admin — Setup (`/admin/events/[id]`)
- Create/edit/delete events; duplicate an event (copies teams, games, criteria — not scores).
- Teams: add, rename, recolour, reorder, delete.
- Games builder: add, reorder (drag or up/down), duplicate, delete.
  - Title, description, scoring mode, points mode, multiplier, placement points.
  - Criteria list: add/remove/reorder; label, description, input type, min/max/step, weight.
  - Quick presets: "Karaoke (5 × 1–5)", "Single score (0–10)", "Points (number)", "Win/Lose (0–1)".
  - Admin notes + judge notes (multiline).
- Judges (judged games only):
  - Nominate judges by name → each gets a personal link (copy button + QR code).
  - Toggle the open link on/off; anyone opening it types their name and becomes a judge.
  - Revoke a judge (link stops working, their scores excluded).
- Share panel: scoreboard link + QR, all judge links per game.

### 4.2 Admin — Control room (`/admin/events/[id]/live`)
This is the screen used during the night. Must be fast and hard to mess up.
- Game switcher: Prev / Next buttons + list of all games with status (upcoming / live / done).
  Setting a game as current marks it `live` and shows it on the scoreboard.
- Current game panel:
  - Scoring grid: rows = teams, columns = criteria, using the same block/number inputs.
    - Direct mode: admin types/taps here. Autosaves.
    - Judged mode: shows per-team average per criterion, a judge-progress matrix
      (✓ per judge per team), and per-judge breakdown on expand. Admin can override a cell
      (override wins over judge average; clearly marked; can be cleared).
  - Spotlight: pick "now performing" team — judges see it highlighted.
  - Lock judging toggle (judges become read-only).
  - Mark game done.
  - Admin notes visible.
- Bonus/penalty: per team quick buttons (+1, +5, +10, −5) and custom amount + reason.
  Recent adjustments list with undo.
- Scoreboard visibility: **Visible / Frozen / Hidden** (see 4.3). Big obvious toggle.
- "Open scoreboard" button (new tab) + "Reveal mode" button (see 4.3).
- Keyboard shortcuts: `N` next game, `P` prev game, `H` cycle visibility, `?` help.

### 4.3 Scoreboard (`/s/[token]`)
- Projector-first, 16:9, readable from the back of a hall.
- Shows: event name, current game title, team standings (rank, name, colour, total points),
  optionally per-game points columns for completed games.
- Updates live (< 1s) when admin changes anything. Rank changes animate.
- **Visible** — live totals.
- **Frozen** — shows totals as they were the moment it was frozen, with a subtle "scores frozen" note.
  Server stores the snapshot; live scores are not sent.
- **Hidden** — no scores sent at all. Shows team names (no order implied — alphabetical) and the current game, with a "scores are hidden" state.
- **Reveal mode** (admin-triggered): scoreboard reveals final standings last place → first,
  one team per admin click ("Reveal next"), then sets visibility to Visible.
- Auto-reconnects; also polls every 10s as a fallback. Shows a small offline dot if disconnected.
- Fullscreen button; hides cursor after inactivity.

### 4.4 Judge (`/j/[token]`)
- Mobile-first. Shows game title, judge notes, and their own name.
- One card per team (spotlighted team pinned on top + highlighted).
- Each card: one block row per criterion (e.g. 1 2 3 4 5 big tap targets) with the criterion
  label + description; number criteria get a stepper.
- Autosaves on every tap; shows saved ✓ / saving / error per card.
- Judges see only their own scores — never other judges' or totals.
- If judging locked or game done: read-only with a message. If revoked: "This link is no longer active."
- Open link (`/jo/[token]`): enter name → creates judge → redirects to personal link and stores it
  in localStorage so a refresh keeps them in.

## 5. Non-functional
- Live latency target < 1s on normal Wi-Fi.
- Works with ~10 teams, ~20 games, ~10 judges per game without lag.
- No data loss on refresh; all state server-side.
- Accessible: visible focus, sufficient contrast, tap targets ≥ 44px.

## 6. Out of scope (v1)
- Individual contestants within teams (stretch: `participants` per team).
- Multiple admins / co-hosts (stretch).
- Timers/buzzers (stretch).