From 0030d4d2c25fecbb6ab28cdd51dc589ddcffd57b Mon Sep 17 00:00:00 2001 From: Mikkel Georgsen Date: Sun, 1 Mar 2026 01:59:26 +0100 Subject: [PATCH] docs(01): capture phase context --- .../phases/01-tournament-engine/01-CONTEXT.md | 137 ++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 .planning/phases/01-tournament-engine/01-CONTEXT.md diff --git a/.planning/phases/01-tournament-engine/01-CONTEXT.md b/.planning/phases/01-tournament-engine/01-CONTEXT.md new file mode 100644 index 0000000..48a4a82 --- /dev/null +++ b/.planning/phases/01-tournament-engine/01-CONTEXT.md @@ -0,0 +1,137 @@ +# Phase 1: Tournament Engine - Context + +**Gathered:** 2026-03-01 +**Status:** Ready for planning + + +## Phase Boundary + +A complete tournament runs from start to finish in an x86 LXC container with a working touch-friendly operator (TD) UI — demoable at a venue by pointing any device at the container. Go backend with embedded LibSQL, NATS JetStream, WebSocket hub. SvelteKit frontend embedded via go:embed. Covers: clock, blinds, financials, players, tables, seating, multi-tournament, and the full TD interface. + +Note: The operator throughout this system is the **Tournament Director (TD)** — use this term consistently. + + + + +## Implementation Decisions + +### Tournament Setup Flow +- **Template-first creation** — TD picks from saved tournament templates, everything pre-fills, tweak what's needed for tonight, hit Start +- **Templates are compositions of reusable building blocks** — a template is NOT a monolithic config. It references: + - Chip set (denominations, colors, values — venue-level) + - Blind structure (level progression, antes, breaks) + - Payout structure (tiered by entry count — see Payout Structure below) + - Buy-in config (entry cost, rake splits, rebuy/add-on rules) + - Points formula (league scoring — venue-level, reused across seasons) +- **Local changes by default** — when creating a tournament from a template, the TD gets a copy. Edits only affect that tournament. To change the actual reusable block, go to template management +- **Dedicated template management area** — create from scratch, duplicate/edit existing, save tournament config as new template +- **Built-in starter templates** ship with the app (Turbo, Standard, Deep Stack, WSOP-style) so day one has something to pick from +- **Structure wizard** lives in template management — input player count, starting chips, desired duration, denominations → generates a blind structure to save as a block +- **Minimum player threshold** — configured in tournament metadata (typically 8-9), Start button unavailable until met +- **Chip bonuses** — configurable per tournament: early signup bonus (before a date/time or first X players) and punctuality bonus (showed up on time) +- **Late registration soft lock with admin override** — when cutoff hits, registration locks but admin can push through a late entry (logged in audit trail). Some tournaments have no late reg at all (registration closes at start) + +### Payout Structure +- **Entry-count brackets with tiered prizes** — standalone reusable building block, example: + - 8–20 entries → 3 prizes (50% / 30% / 20%) + - 21–30 entries → 4 prizes (45% / 26% / 17% / 12%) + - 31–40 entries → 5 prizes (42% / 26% / 16% / 11% / 5%) + - 41–50 entries → 6 prizes (40% / 24% / 14% / 10% / 7% / 5%) +- **Entry count = unique entries only** — not rebuys or add-ons +- **Prize rounding** — all prizes round down to nearest venue-configured denomination (e.g. 50 DKK in Denmark, €5 elsewhere). No coins, no awkward change +- **Bubble prize** — happens in ~70% of tournaments. When remaining players exceed paid positions (e.g. 8 left, 7 paid), all remaining players can unanimously agree to create a bubble prize: + - Typically around the buy-in amount + - Funded by shaving from top prizes (mostly 1st–3rd, sometimes 4th–5th) + - TD flow: "Add bubble prize" → set amount → system shows redistribution across top prizes → confirm + - Must be fast and intuitive — not buried in menus, this happens constantly + +### TD Workflow During Play +- **Overview tab priority** (top to bottom): + 1. Clock & current level (biggest element) + 2. Time to next break + 3. Player count (registered / remaining / busted) + 4. Table balance status (are tables even or needs attention) + 5. Financial summary (prize pool, entries, rebuys) + 6. Recent activity feed (last few actions) +- **Bust-out flow**: tap Bust → pick table → pick seat → system shows player name for verification → confirm → select hitman (mandatory in PKO tournaments, optional otherwise) → done +- **PKO (Progressive Knockout)**: when template defines PKO, bounty transfer is part of the bust flow (half to hitman, half added to their own bounty, chain tracked) +- **Buy-in flow**: search/select player → auto-seat suggests optimal seat → TD can override (accessibility needs, keep-apart situations like couples) → confirm → receipt +- **Multi-tournament switching**: TD chooses tabs at top OR split view — phone likely tabs, tablet landscape could do split view +- **Undo is critical** — bust-outs, rebuys, add-ons, buy-ins can all be undone with full re-ranking. Miscommunication between TD and dealers happens often + +### Seating & Balancing +- **Oval table view (default)** — top-down view with numbered seats, player names in seats, empty seats visible. Switchable to list view for density (10+ table tournaments) +- **Balancing is TD-driven, system-assisted**: + 1. System alerts: tables are unbalanced + 2. TD requests suggestion: system says "move 1 from Table 1 to Table 4" + 3. TD announces to the floor, assistant facilitates + 4. Assistant reports back: "Seat 3 to Seat 5" — TD taps two seat numbers, done (minimal touches) + 5. Suggestion is **live and adaptive** — if Table 1 loses a player before the move happens (e.g. bust during ongoing hand), system recalculates or cancels +- **Break Table is fully automatic** — system knows all open seats, distributes players evenly, TD just sees the result ("Player X → Table 1 Seat 4") +- **No drag-and-drop in Phase 1** — tap-tap flow for all moves + +### End-Game & Payouts +- **Flexible chop/deal support** — all remaining players participate in a deal, nobody leaves while others play on. Supported scenarios: + - ICM calculation (TD inputs chip stacks, system calculates each player's share) + - Custom split (players agree on % or fixed amount) + - Partial chop (split some money, play on for remaining + league points) + - Any number of players (not just heads-up — 4-way deals after 12 hours are real) +- **Prize money and league positions are independent** — money can be chopped but positions still determined by play for points +- **Tournament auto-closes** when one player remains — no manual "end tournament" button +- **Receipts configurable per venue**: off / digital / print / both. Player and venue can always see tournament participation in the system regardless of receipt setting + +### Claude's Discretion +- Loading skeleton and animation design +- Exact spacing, typography, and component sizing +- Error state handling and messaging +- Toast notification behavior and timing +- Activity feed formatting +- Thermal printer receipt layout +- Internal data structures and state management patterns + + + + +## Specific Ideas + +- The bust-out flow must be as few taps as possible — TD is under time pressure during a running tournament +- Balancing recording should be two taps (source seat, destination seat) after the system suggests table-to-table +- Bubble prize creation needs to be fast and prominent — it happens in 70% of tournaments +- "Add bubble prize" should be easily accessible, not buried in settings +- Template building blocks should feel like LEGO — pick chip set, pick blind structure, pick payout table, name it, done +- The system should adapt to the chaos of live poker — hands in progress during balancing, players busting mid-move, deals negotiated at 2am after 12 hours of play + + + + +## Existing Code Insights + +### Reusable Assets +- No existing code — greenfield project + +### Established Patterns +- No established patterns yet — Phase 1 sets the foundation + +### Integration Points +- Go binary serves SvelteKit via go:embed +- WebSocket hub for real-time state to all connected clients +- LibSQL for local persistence +- NATS JetStream for event durability +- Catppuccin Mocha dark theme (UI-05) + + + + +## Deferred Ideas + +- **Drag-and-drop seat moves** — UI polish, add after core tap-tap flow works (future Phase 1 enhancement or later) +- **PWA seat move notifications** — when a player is moved (balancing or table break), notify them in the PWA with new table/seat — Phase 2 +- **"Keep apart" player marking** — TD marks players who shouldn't be at the same table (couples, etc.), auto-seating respects it — evaluate for Phase 1 or later +- **Chip bonus for early signup/punctuality** — captured in decisions, evaluate complexity during planning + + + +--- + +*Phase: 01-tournament-engine* +*Context gathered: 2026-03-01*