# PINTRUSH — Website & App Build Specification

Version: 2.0 | October 2026 | Supersedes: CrowdPlay Build Spec v1.0
Domain: **pintrush.com** (unregistered as of 2026-10-29 per Verisign RDAP — register before building)
Backup domains (also unregistered 2026-10-29): lastcallrush.com, tapbrawl.com, barrushlive.com

> Rename rationale: crowdplay.com has been registered since 2006. "PintRush" is short, bar-specific, and ties directly to the signature game (**The Rush**). Run a USPTO trademark search (Class 41 – entertainment services; Class 9/42 – software) before launch.

---

## 1. Instructions for Claude

You are the lead product engineer and game designer. Build a production-minded MVP of **PintRush**: a public marketing website plus a multi-tenant, browser-based bar entertainment SaaS. The signature game is **The Rush** — live trivia, music recognition, bingo-style board completion, table competition, and power-ups.

Rules of engagement:
- Work incrementally: inspect the repo → short plan → working code with tests.
- Never pretend external services, licensing, deployment, DNS, or payments are configured.
- Ask for credentials only when required; ship local development defaults.
- At each step report: what changed, files created, commands to run, tests passing/failing, known limitations, next steps.
- Prefer a functioning minimal implementation over elaborate mockups.

### Product promise

**The Bar Is the Arena. Everyone Plays.** Bars run games on TVs; patrons join from phones via QR code — no app install, no registration.

| Mode | Length | Host required | Leaderboard |
|---|---|---|---|
| Always-on | 3–5 min rounds, continuous | No | Nightly |
| Championship | 45–60 min scheduled show | Yes | Event (separate) |

Optional accounts and cross-venue Passport progression are post-MVP.

---

## 2. Surfaces

### 2.1 Public marketing website (pintrush.com) — NEW

| Route | Purpose |
|---|---|
| `/` | Hero ("The Bar Is the Arena"), 3-step how-it-works (Scan → Play → Win the Night), live demo video/animation, venue testimonials placeholder, CTA |
| `/how-it-works` | Always-on vs Championship, The Rush rules, power-ups, TV + phone screenshots |
| `/for-venues` | Benefits for owners: dwell time, slow-night traffic, zero hardware beyond a TV, setup in minutes |
| `/pricing` | Tier cards (Section 9) labeled "Pilot pricing" — CTA = Join Pilot, not checkout |
| `/pilot` | Venue pilot application form: venue name, address, contact, # TVs, busiest nights, current entertainment. Stores to `PilotLead`; email notification to admin (log-only in dev) |
| `/demo` | Self-running sandbox: one TV view + embedded phone view in a demo room with bots |
| `/faq` | No-app join, privacy, legality (no wagering), content licensing |
| `/legal/privacy`, `/legal/terms` | Placeholder templates flagged for lawyer review |

Requirements: static/SSG where possible, Lighthouse ≥ 90 performance/accessibility/SEO, OpenGraph images, sitemap.xml, robots.txt, basic analytics (privacy-respecting, cookie-less by default), spam protection on forms (honeypot + rate limit).

### 2.2 Application surfaces

| Role | Surface | Capabilities |
|---|---|---|
| Guest player | `/join/[venueCode]` → `/play/[roomId]` | Scan QR, nickname, answer timed questions, 3×3 board, score, power-ups, leaderboard |
| TV display | `/tv/[roomId]?t=[tvToken]` | Read-only 16:9: join QR, question, countdown, results, leaderboards, attract mode. Never shows answers before lock |
| Venue host | `/host`, `/host/events/[id]` | Auth'd: create/schedule/start/pause/resume/end events, pick packs, moderate nicknames, metrics |
| Platform admin | `/admin` | Venues, content packs, subscription states, pilot leads, support tools |

TV tokens are display-scoped only; they must never authorize host actions.

---

## 3. Signature game: The Rush

### 3.1 Scoring table

| Event | Points | Limit |
|---|---|---|
| Correct — standard | 100 | per question |
| Correct — difficult | 150 | per question |
| Speed bonus | 0–50 | per correct answer |
| Line (row/col/diagonal) | 250 | once per distinct line (8 possible) |
| Full board | 500 | once |
| Table challenge win | 200 | per challenge, normalized for teams |
| Incorrect / no answer | 0 | — |

**Speed bonus formula (server-authoritative):**
`bonus = round(50 × max(0, 1 − (t_answer − t_open − grace) / (window − grace)))`
- `t_open` = server timestamp when question opened; `t_answer` = server receive time.
- `grace` = 750 ms latency allowance (answers inside grace get full 50).
- Client clock is never used.

### 3.2 Board fairness — default design (resolves v1 ambiguity)

- 9 categories per game pack, e.g. Pop Culture, History, Sports, Science, Geography, Music, Food & Drink, Movies/TV, Wildcard-eligible General.
- **Board = Latin-square-derived template**: every player's board contains each of the 9 categories exactly once; templates are permutations from a fixed set of 8 balanced layouts (each category appears in a corner, edge, and center position equally often across the set) so no player has a structurally easier line.
- **10-question game schedule:** 9 questions, one per category (deterministic order per pack, shuffled by seed), plus **Q10 = Wildcard**: a correct answer activates any one unactivated tile of the player's choice (server-validated).
- Result: every player has an identical number of activation opportunities (10) and can reach full board with 9 correct of 10.
- Required tests: (a) every generated board contains all 9 categories once; (b) across the template set, each category's positional distribution is equal; (c) simulated perfect player reaches full board; (d) simulated games with identical answer patterns yield identical scores regardless of template.

### 3.3 Tie-breaks (deterministic, shown on TV)

1. Higher total points → 2. More correct answers → 3. Lower cumulative server-measured answer time on correct answers → 4. Earlier final correct submission timestamp.

### 3.4 Team scoring

Team score = mean of member scores (players with ≥ 1 answer). Teams of 1 rank in a separate "Solo" board or are merged at host's choice.

### 3.5 Power-ups

Earned by completing a line; never sold. One use of each type per championship. All consumption atomic and idempotent (unique `(playerSessionId, eventId, powerUpType)`).

| Power-up | When | Effect | MVP |
|---|---|---|---|
| Double Down | Before question opens | Wager 100: correct = +200 extra, wrong = −100. Requires balance ≥ 100 | Yes |
| Second Chance | Before submitting (MC only) | Server removes one incorrect option | Yes |
| Category Swap | Between questions | Swaps one unactivated tile with another unactivated tile **on the same board** (position swap, category set unchanged → fairness preserved) | Yes |

### 3.6 Championship format (50 min default)

| Time | Segment |
|---|---|
| 0–5 | Join, nicknames, teams, countdown |
| 5–15 | The Rush — standard questions |
| 15–25 | Music Mayhem — song/artist questions, original or licensed only; no lyric reproduction |
| 25–35 | Table Wars — normalized team challenges |
| 35–45 | Power Round — boards and power-ups |
| 45–50 | Final Rush — top 5 play 5 questions; everyone else plays a non-scoring prediction game |

Championship scores start at zero; always-on XP/badges grant no championship advantage.

### 3.7 Always-on mode

- Venue operating schedule; rounds auto-start back-to-back with a 60 s break.
- Late join: allowed until question 3 opens; otherwise player waits for next round (UI shows countdown).
- Nightly leaderboard separate from championship.
- TV attract mode between rounds: QR, next-round timer, nightly top 10, next championship time.
- No paid entry or wagering.

---

## 4. MVP scope

### Build
1. Marketing site (Section 2.1) with pilot form.
2. Multi-tenant venues, isolated rooms.
3. QR join, nickname validation, profanity filter, duplicate-name suffixing ("Mike", "Mike 2").
4. Responsive player UI, 16:9 TV UI, auth'd host dashboard.
5. Question lifecycle: `pending → open → locked → revealed → completed`.
6. WebSocket sync, reconnect, full state resync.
7. Scoring, balanced boards, line/full-board bonuses, all three power-ups.
8. Always-on scheduler + host-run championship.
9. Leaderboards, teams, content-pack selection.
10. Analytics: unique guest sessions, joins, rounds completed, repeat participation, event counts.
11. Seed packs: original trivia only (≥ 200 questions across 9 categories). No recordings, no lyrics.
12. Tests: scoring, timing, tenant isolation, idempotency, fairness.
13. README, `.env.example`, Docker Compose, deployment notes.

### Defer
National leagues, karaoke, commercial music catalogs, Passport/social graph, sponsor marketplace, cash prizes, POS integration, Stripe billing (keep `Plan`/`Entitlement` tables so billing drops in later).

---

## 5. Stack

| Layer | Choice |
|---|---|
| Web (marketing + player + TV + host) | Next.js (App Router) + React + TypeScript + Tailwind |
| Real-time game server | Separate long-running Node.js/TypeScript service (Socket.IO or `ws`) — not serverless |
| DB | PostgreSQL + Prisma |
| Ephemeral state / pub-sub | Redis; in-memory adapter for local dev (documented single-process limit) |
| QR | `qrcode` |
| Local infra | Docker Compose (Postgres, Redis) |
| Tests | Vitest (unit/integration), Playwright (join → play → host flows) |
| Repo | pnpm monorepo: `apps/web`, `apps/game-server`, `packages/engine` (pure game logic), `packages/db`, `packages/protocol` (zod schemas) |

Keep all scoring/board logic in `packages/engine` as pure functions so it is fully unit-testable.

---

## 6. Domain model

Venue, VenueUser, Room, Event, GameSession, Round, PlayerSession, Team, TeamMembership, QuestionPack, Question, BoardTemplate, PlayerBoard, BoardTile, AnswerSubmission, ScoreEvent, PowerUpGrant, PowerUpUse, LeaderboardSnapshot, AuditEvent, PilotLead, Plan, Entitlement.

Required: `venueId` on every tenant row, UUIDs, server timestamps, status enums, `version` for optimistic concurrency, idempotency keys.

Unique constraints:
- `AnswerSubmission(playerSessionId, questionId)`
- `BoardTile` activation `(playerBoardId, position)`
- `ScoreEvent(playerSessionId, gameSessionId, kind, refId)` (line/full-board awards)
- `PowerUpUse(playerSessionId, eventId, type)`

Guest tokens: signed (HMAC/JWT), scoped to `venueId + roomId`, short TTL, rotated on reconnect.

---

## 7. Real-time protocol

| Direction | Events |
|---|---|
| Client → server | `room.join`, `answer.submit`, `powerup.activate`, `state.request` |
| Server → client | `room.state`, `round.start`, `question.open`, `question.lock`, `answer.result`, `board.updated`, `score.updated`, `leaderboard.updated`, `round.complete`, `event.complete` |
| Host → server | `event.start`, `event.pause`, `event.resume`, `event.end`, `round.advance`, `nickname.moderate` |

Every message: zod-validated payload, `seq` number per room, ack `{ok, error?}`, idempotency key on all client mutations. Reconnect = `state.request` with last `seq`; server replies with full snapshot. Never trust client score or clock. Rate-limit per socket.

---

## 8. UI direction

- Palette: dark navy base, electric violet, cyan, hot accent (amber/lime) for celebrations.
- TV: readable at 30 ft — question text ≥ 48 px at 1080p, countdown ≥ 160 px.
- Player: one-handed, bottom-anchored answer buttons, 48 px minimum tap targets, visible focus states, `prefers-reduced-motion` respected.
- Marketing site shares the same identity; hero shows animated TV + phone mock.

---

## 9. Pricing (pilot hypotheses — display only, no billing)

| Tier | Price/venue/mo | Includes |
|---|---|---|
| Starter | $79 | Always-on games, TV display, QR join |
| Pro | $149 | + Championships, power-ups, venue leagues, reporting |
| Network | $249 | + Multi-venue features (when available) |

---

## 10. Security, legal, reliability

- Tenant isolation in API and DB queries (tests required).
- RBAC, rate limiting, server-side validation, nickname moderation.
- Original or licensed content only; public-performance rights reviewed separately.
- No paid wagering. Legal review per jurisdiction before valuable prizes.
- Minimal PII; guest data auto-purged after 90 days; pilot leads retained until deleted.
- Graceful handling: phone disconnects, late joins, host drops, server restarts, double submits, races, TV refresh.
- Append-only `AuditEvent` log so any disputed result can be reconstructed.

---

## 11. Pilot metrics (hypotheses, not benchmarks)

Pilot 3–5 bars (Long Island first).

| Metric | Target |
|---|---|
| Identifiable players returning within 30 days | ≥ 30% |
| Players playing > 1 round per visit | ≥ 50% |
| Venues willing to convert to paid | ≥ 60% |

Also track round completion, answer latency, reconnect rate, host effort, perceived fairness.

---

## 12. Development sequence

| Step | Deliverable |
|---|---|
| 1 — Plan | Inspect repo; scaffold monorepo if empty; architecture, entities, protocol, plan, resolved ambiguities |
| 2 — Vertical slice | One venue/room, QR join, synced 10-question Rush game, board, scoring, TV leaderboard, seed questions, scoring tests |
| 3 — Mechanics | Balanced templates, lines, power-ups, timers, tie-breaks, duplicate/reconnect tests |
| 4 — Operations | Host dashboard auth, scheduling, always-on, tenant isolation, analytics |
| 5 — Marketing site | All Section 2.1 routes, pilot form, demo room, SEO |
| 6 — Polish | Visual design, accessibility, Playwright E2E, production deployment guide (e.g. Vercel for web + Fly.io/Render for game server + managed Postgres/Redis) |

---

## 13. First instruction to execute

**Inspect the current directory. If empty, create the PintRush monorepo. Complete Step 1 and Step 2 now: a working local app with player join, TV display, host start/advance controls, one complete 10-question Rush game using the Section 3.2 board design, and passing automated scoring and fairness tests. Do not stop after a proposal.**