# Phase 1: Tournament Engine - Research

**Researched:** 2026-03-01
**Domain:** Full-stack tournament management — Go backend (LibSQL, NATS JetStream, WebSocket), SvelteKit frontend (embedded via go:embed), poker domain logic (clock, blinds, financials, seating, ICM)
**Confidence:** HIGH (core stack verified via official sources and docs)

## Summary

Phase 1 is a greenfield full-stack build: a single Go binary embedding LibSQL (local SQLite fork), NATS JetStream (event durability), and a WebSocket hub, serving a SvelteKit SPA via `go:embed`. The binary runs in an x86 LXC container and provides a touch-friendly Tournament Director (TD) UI for managing a complete poker tournament lifecycle.

The Go backend stack is well-established. LibSQL provides a local-first SQLite-compatible database via `go-libsql` (CGO required, no tagged releases — pin to commit hash). NATS server embeds programmatically with JetStream enabled for append-only event durability (`sync_interval: always` is mandatory for single-node per the December 2025 Jepsen finding). The WebSocket hub uses `coder/websocket` (v1.8.14, formerly nhooyr.io/websocket) for idiomatic Go context support. HTTP routing uses `go-chi/chi` v5 for its lightweight middleware composition. Authentication is bcrypt-hashed PINs producing local JWTs via `golang-jwt/jwt` v5.

The SvelteKit frontend uses Svelte 5 with runes (the new reactivity model replacing stores) and `adapter-static` to prerender a SPA embedded in the Go binary. Catppuccin Mocha provides the dark theme via CSS custom properties from `@catppuccin/palette`. The operator UI follows a mobile-first bottom-tab layout with FAB quick actions, persistent clock header, and 48px touch targets.

The poker domain has several non-trivial algorithmic areas: ICM calculation (factorial complexity, needs Monte Carlo approximation beyond ~15 players), blind structure wizard (backward calculation from target duration to level progression), table balancing (TDA-compliant seat assignment with blind position awareness), and PKO bounty chain tracking (half bounty to hitman, half added to own bounty).

**Primary recommendation:** Build as a monolithic Go binary with clean internal package boundaries (clock, financial, seating, player, audit). Use event-sourced state changes written to both NATS JetStream (for real-time broadcast) and LibSQL (for persistence and query). All financial math uses int64 cents with a CI gate test proving zero-deviation payout sums.

<user_constraints>

## User Constraints (from CONTEXT.md)

### Locked Decisions

- **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, Blind structure, Payout structure, Buy-in config, Points formula (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
- **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)
- **Structure wizard** lives in template management — input player count, starting chips, duration, denominations -> generates a blind structure
- **Minimum player threshold** — configured in tournament metadata, Start button unavailable until met
- **Chip bonuses** — configurable per tournament: early signup bonus, punctuality bonus
- **Late registration soft lock with admin override** — when cutoff hits, registration locks but admin can push through (logged in audit trail)
- **Payout structure as standalone reusable building block** — entry-count brackets with tiered prizes
- **Entry count = unique entries only** — not rebuys or add-ons
- **Prize rounding** — round down to nearest venue-configured denomination (e.g. 50 DKK, EUR 5)
- **Bubble prize** — fast and prominent, "Add bubble prize" easily accessible, funded by shaving top prizes
- **Overview tab priority** — Clock > Time to break > Player count > Table balance > Financial summary > Activity feed
- **Bust-out flow** — tap Bust -> pick table -> pick seat -> verify name -> confirm -> select hitman -> done
- **PKO (Progressive Knockout)** — bounty transfer part of bust flow (half to hitman, half added to own bounty)
- **Buy-in flow** — search/select player -> auto-seat -> TD override option -> confirm -> receipt
- **Multi-tournament switching** — tabs at top (phone) or split view (tablet landscape)
- **Undo is critical** — bust-outs, rebuys, add-ons, buy-ins can all be undone with full re-ranking
- **Oval table view (default)** — top-down view with numbered seats, switchable to list view
- **Balancing is TD-driven, system-assisted** — system alerts, TD requests suggestion, TD announces, assistant reports, two-tap recording
- **Break Table is fully automatic** — system distributes evenly, TD sees result
- **No drag-and-drop in Phase 1** — tap-tap flow for all moves
- **Flexible chop/deal support** — ICM, custom split, partial chop, any number of players
- **Prize money and league positions are independent**
- **Tournament auto-closes** when one player remains
- **Receipts configurable per venue** — off / digital / print / both
- **Operator is the Tournament Director (TD)** — use this term consistently

### 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

### Deferred Ideas (OUT OF SCOPE)

- **Drag-and-drop seat moves** — future Phase 1 enhancement or later
- **PWA seat move notifications** — Phase 2
- **"Keep apart" player marking** — evaluate for Phase 1 or later
- **Chip bonus for early signup/punctuality** — captured in decisions, evaluate complexity during planning

</user_constraints>

<phase_requirements>

## Phase Requirements

| ID | Description | Research Support |
|----|-------------|-----------------|
| ARCH-01 | Single Go binary on x86 LXC with embedded LibSQL, NATS JetStream, WebSocket hub | go-libsql local-only mode (`sql.Open("libsql", "file:"+path)`), embedded nats-server with JetStream, coder/websocket hub pattern |
| ARCH-03 | All financial values stored as int64 cents — never float64 | Standard Go int64 arithmetic, CI gate test pattern documented |
| ARCH-04 | NATS JetStream embedded with `sync_interval: always` for durability | Jepsen 2.12.1 finding confirms mandatory for single-node; embedded server opts `JetStream: true` + sync config |
| ARCH-05 | WebSocket hub broadcasts within 100ms | coder/websocket concurrent writes, custom hub with connection registry pattern |
| ARCH-06 | SvelteKit frontend via `//go:embed` | adapter-static + `//go:embed all:build` + SPA fallback handler pattern |
| ARCH-07 | Leaf is sovereign — cloud never required | Local LibSQL file, embedded NATS, all logic in Go binary |
| ARCH-08 | Append-only audit trail for every state-changing action | Event-sourced audit table in LibSQL + NATS JetStream publish for real-time |
| AUTH-01 | Operator PIN login -> local JWT (bcrypt in LibSQL) | golang-jwt/jwt v5 + golang.org/x/crypto/bcrypt, offline-capable |
| AUTH-03 | Operator roles: Admin, Floor, Viewer | JWT claims with role field, middleware enforcement on chi routes |
| CLOCK-01 | Countdown timer per level, second-granularity display, ms-precision internal | Go time.Ticker + monotonic clock, server-authoritative time |
| CLOCK-02 | Separate break durations with distinct visual treatment | Level type enum (round/break), frontend conditional styling |
| CLOCK-03 | Pause/resume with visual indicator across all displays | Clock state machine (running/paused/stopped), WebSocket broadcast |
| CLOCK-04 | Manual advance forward/backward between levels | Clock engine level index navigation |
| CLOCK-05 | Jump to any level by number | Direct level index set on clock engine |
| CLOCK-06 | Total elapsed time display | Tracked from tournament start, pauses excluded |
| CLOCK-07 | Configurable warning thresholds with audio/visual | Threshold config per level, play_sound action on WebSocket, CSS animation triggers |
| CLOCK-08 | Clock state authoritative on Leaf; 1/sec normal, 10/sec final 10s | Server-side tick emitter with dynamic interval |
| CLOCK-09 | Reconnecting clients receive full clock state | WebSocket connection handler sends current snapshot on connect |
| BLIND-01 | Unlimited configurable levels (round/break, game type, SB/BB, ante, duration, chip-up, notes) | Level struct with all fields, array in blind structure entity |
| BLIND-02 | Big Blind Ante support alongside standard ante | Separate ante and bb_ante fields per level |
| BLIND-03 | Mixed game rotation (HORSE, 8-Game) | Game type per level, rotation sequence in structure |
| BLIND-04 | Save/load reusable blind structure templates | Template CRUD in LibSQL, building block pattern |
| BLIND-05 | Built-in templates (Turbo, Standard, Deep Stack, WSOP-style) | Seed data on first boot |
| BLIND-06 | Structure wizard | Algorithm: target duration -> final BB -> geometric curve -> nearest chip denominations |
| CHIP-01 | Define denominations with colors (hex) and values | Chip set entity (venue-level building block) |
| CHIP-02 | Chip-up tracking per break | Level flag + chip-up denomination reference |
| CHIP-03 | Total chips in play calculation | Sum of (active players * starting chips) + rebuys + add-ons |
| CHIP-04 | Average stack display | Total chips / remaining players |
| FIN-01 | Buy-in configuration (amount, chips, rake, bounty, points) | Buy-in config entity as building block, int64 cents |
| FIN-02 | Multiple rake categories (staff, league, house) | Rake split array in buy-in config |
| FIN-03 | Late registration cutoff (by level, by time, or both) | Cutoff config with dual-condition logic |
| FIN-04 | Re-entry support (distinct from rebuy) | Separate transaction type, new entry after bust |
| FIN-05 | Rebuy configuration (cost, chips, rake, points, limits, cutoff, chip threshold) | Rebuy config entity with all parameters |
| FIN-06 | Add-on configuration (cost, chips, rake, points, window) | Add-on config entity |
| FIN-07 | Fixed bounty system (cost, chip, hitman tracking, chain tracking, cash-out) | PKO bounty entity per player, half-split on elimination, chain tracked in audit trail |
| FIN-08 | Prize pool auto-calculation | Sum of all entries * entry amount - total rake, int64 cents |
| FIN-09 | Guaranteed pot support (house covers shortfall) | Guarantee config field, shortfall = guarantee - actual pool |
| FIN-10 | Payout structures (percentage, fixed, custom) with rounding | Payout building block, round-down to venue denomination, bracket selection by entry count |
| FIN-11 | Chop/deal support (ICM, chip-chop, even-chop, custom) | ICM: Malmuth-Harville algorithm (Monte Carlo for >15 players), custom split UI |
| FIN-12 | End-of-season withholding | Rake category marked as season reserve |
| FIN-13 | Every financial action generates receipt | Transaction log with receipt rendering |
| FIN-14 | Transaction editing with audit trail and receipt reprint | Undo/edit creates new audit entry referencing original |
| PLYR-01 | Player database persistent on Leaf (LibSQL) | LibSQL local file, player table with UUID PK |
| PLYR-02 | Search with typeahead, merge duplicates, import CSV | FTS5 (SQLite full-text search) for typeahead, merge logic, CSV import endpoint |
| PLYR-03 | QR code generation per player | Go QR library (e.g. skip2/go-qrcode), encodes player UUID |
| PLYR-04 | Buy-in flow (search -> confirm -> auto-seat -> receipt -> display update) | Multi-step transaction: financial entry + seat assignment + WebSocket broadcast |
| PLYR-05 | Bust-out flow (select -> hitman -> bounty -> rank -> rebalance -> display) | Multi-step: bust record + bounty transfer + re-rank + balance check + broadcast |
| PLYR-06 | Undo for bust-out, rebuy, add-on, buy-in with re-ranking | Reverse transaction in audit trail, recalculate rankings and balances |
| PLYR-07 | Per-player tracking (chips, time, seat, moves, rebuys, add-ons, bounties, prize, points, net, history) | Computed from transaction log and current state |
| SEAT-01 | Tables with configurable seat counts (6-max to 10-max) | Table entity with seat_count, name/label |
| SEAT-02 | Table blueprints (save venue layout) | Blueprint entity as venue-level template |
| SEAT-03 | Dealer button tracking | Button position field per table, advanced on bust/balance |
| SEAT-04 | Random initial seating on buy-in (fills evenly) | Random seat assignment algorithm: find table with fewest players, random empty seat |
| SEAT-05 | Auto balancing suggestions with operator confirmation | TDA-compliant algorithm: size difference threshold, move fairness, button awareness, dry-run preview |
| SEAT-06 | Drag-and-drop manual moves on touch interface | DEFERRED in Phase 1 — tap-tap flow instead |
| SEAT-07 | Break Table action (dissolve and distribute) | Distribute players from broken table to remaining tables evenly, respecting blind position |
| SEAT-08 | Visual top-down table layout, list view, movement screen | Oval SVG table component, list view alternative, move confirmation screen |
| SEAT-09 | Hand-for-hand mode | Clock pause + per-hand level decrement mode |
| MULTI-01 | Multiple simultaneous tournaments with independent state | Tournament-scoped state (clock, financials, players all keyed by tournament ID) |
| MULTI-02 | Tournament lobby view | List of active tournaments with status summary |
| UI-01 | Mobile-first bottom tab bar (Overview, Players, Tables, Financials, More) | SvelteKit layout with bottom nav component |
| UI-02 | FAB for quick actions (Bust, Buy In, Rebuy, Add-On, Pause/Resume) | Expandable FAB component with context-aware actions |
| UI-03 | Persistent header (clock, level, blinds, player count) | Fixed header component subscribing to clock WebSocket |
| UI-04 | Desktop/laptop sidebar navigation | Responsive layout: bottom tabs on mobile, sidebar on desktop |
| UI-05 | Catppuccin Mocha dark theme (default), Latte light theme | @catppuccin/palette CSS custom properties, theme toggle |
| UI-06 | 48px minimum touch targets, press-state animations, loading states | CSS touch-action, :active states, skeleton loading |
| UI-07 | Toast notifications (success, info, warning, error) | Svelte toast store/rune with auto-dismiss timer |
| UI-08 | Data tables with sort, sticky header, search/filter, swipe actions | Custom table component or thin wrapper, virtual scroll for large lists |

</phase_requirements>

## Standard Stack

### Core

| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| Go | 1.23+ | Backend language | Current stable, required for latest stdlib features |
| github.com/tursodatabase/go-libsql | commit pin (no tags) | Embedded LibSQL database | SQLite-compatible, local-first, CGO required, `sql.Open("libsql", "file:"+path)` |
| github.com/nats-io/nats-server/v2 | v2.12.4 | Embedded NATS server with JetStream | Event durability, append-only streams, embedded in Go process |
| github.com/nats-io/nats.go | latest (v1.49+) | NATS Go client + jetstream package | New JetStream API (replaces legacy JetStreamContext) |
| github.com/coder/websocket | v1.8.14 | WebSocket server | Minimal, idiomatic, context.Context support, concurrent writes, zero deps |
| github.com/go-chi/chi/v5 | v5.2.5 | HTTP router | Lightweight, stdlib-compatible middleware, route grouping |
| github.com/golang-jwt/jwt/v5 | v5.x (latest) | JWT tokens | Standard Go JWT library, 13K+ importers, HS256 signing |
| golang.org/x/crypto | latest | bcrypt for PIN hashing | Standard library extension, production-grade bcrypt |
| Svelte | 5.46+ | Frontend framework | Runes reactivity model, compiled output, small bundle |
| SvelteKit | 2.x | Frontend framework/router | adapter-static for SPA, file-based routing, SSR-capable |
| @sveltejs/adapter-static | latest | SPA build adapter | Prerenders all pages to static HTML for go:embed |
| @catppuccin/palette | latest | Theme colors | Official Catppuccin color palette as CSS/JS, Mocha + Latte flavors |

### Supporting

| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| github.com/skip2/go-qrcode | latest | QR code generation | PLYR-03: Player QR codes for self-check-in |
| github.com/google/uuid | latest | UUID generation | Player IDs, tournament IDs, all entity PKs |
| FTS5 (built into LibSQL/SQLite) | N/A | Full-text search | PLYR-02: Typeahead player search |
| @catppuccin/tailwindcss | latest | Tailwind theme plugin | Only if using Tailwind; otherwise use raw CSS vars from @catppuccin/palette |

### Alternatives Considered

| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| go-chi/chi v5 | Go 1.22+ stdlib ServeMux | Go 1.22 added method+path matching but chi has better middleware composition, route grouping, and ecosystem |
| coder/websocket | gorilla/websocket | gorilla is more battle-tested (6+ years) but coder/websocket is more idiomatic (context support, concurrent writes) and actively maintained by Coder |
| go-libsql | mattn/go-sqlite3 | go-sqlite3 is more mature with tagged releases but doesn't support libSQL extensions and eventual Turso sync in Phase 3 |
| SvelteKit adapter-static | Vite vanilla SPA | SvelteKit provides file-based routing, layouts, and SSR-capability for Phase 2+ |

**Installation (Go):**
```bash
# go.mod — pin go-libsql to specific commit
go get github.com/tursodatabase/go-libsql@<commit-hash>
go get github.com/nats-io/nats-server/v2@v2.12.4
go get github.com/nats-io/nats.go@latest
go get github.com/coder/websocket@v1.8.14
go get github.com/go-chi/chi/v5@v5.2.5
go get github.com/golang-jwt/jwt/v5@latest
go get golang.org/x/crypto@latest
go get github.com/skip2/go-qrcode@latest
go get github.com/google/uuid@latest
```

**Installation (Frontend):**
```bash
npm create svelte@latest frontend -- --template skeleton
cd frontend
npm install @catppuccin/palette
npm install -D @sveltejs/adapter-static
```

## Architecture Patterns

### Recommended Project Structure

```
felt/
├── cmd/
│   └── leaf/
│       └── main.go              # Entry point: starts NATS, LibSQL, HTTP server
├── internal/
│   ├── server/
│   │   ├── server.go            # HTTP server setup, chi router, middleware
│   │   ├── ws/
│   │   │   └── hub.go           # WebSocket hub: connection registry, broadcast
│   │   └── middleware/
│   │       ├── auth.go          # JWT validation middleware
│   │       └── role.go          # Role-based access control
│   ├── auth/
│   │   ├── pin.go               # PIN login, bcrypt verify, JWT issue
│   │   └── jwt.go               # Token creation, validation, claims
│   ├── clock/
│   │   ├── engine.go            # Clock state machine (running/paused/stopped)
│   │   ├── ticker.go            # Server-side tick emitter (1/sec, 10/sec final 10s)
│   │   └── warnings.go          # Threshold detection and alert emission
│   ├── tournament/
│   │   ├── tournament.go        # Tournament lifecycle (create, start, close)
│   │   ├── state.go             # Tournament state aggregation
│   │   └── multi.go             # Multi-tournament management
│   ├── financial/
│   │   ├── engine.go            # Buy-in, rebuy, add-on, bounty transactions
│   │   ├── payout.go            # Prize pool calculation, payout distribution
│   │   ├── icm.go               # ICM calculator (Malmuth-Harville + Monte Carlo)
│   │   ├── chop.go              # Deal/chop flows (ICM, chip-chop, custom)
│   │   └── receipt.go           # Receipt generation
│   ├── player/
│   │   ├── player.go            # Player CRUD, search, merge
│   │   ├── ranking.go           # Live rankings, re-ranking on undo
│   │   └── qrcode.go            # QR code generation
│   ├── seating/
│   │   ├── table.go             # Table management, seat assignment
│   │   ├── balance.go           # Table balancing algorithm
│   │   ├── breaktable.go        # Table break and redistribute
│   │   └── blueprint.go         # Venue layout blueprints
│   ├── blind/
│   │   ├── structure.go         # Blind structure definition and CRUD
│   │   ├── wizard.go            # Structure wizard algorithm
│   │   └── templates.go         # Built-in template seed data
│   ├── template/
│   │   ├── tournament.go        # Tournament template (composition of blocks)
│   │   ├── chipset.go           # Chip set building block
│   │   ├── payout.go            # Payout structure building block
│   │   └── buyin.go             # Buy-in config building block
│   ├── audit/
│   │   ├── trail.go             # Append-only audit log
│   │   └── undo.go              # Undo engine (reverse operations)
│   ├── nats/
│   │   ├── embedded.go          # Embedded NATS server startup
│   │   └── publisher.go         # Event publishing to JetStream
│   └── store/
│       ├── db.go                # LibSQL connection setup
│       ├── migrations/          # SQL migration files
│       └── queries/             # SQL query files (or generated)
├── frontend/
│   ├── src/
│   │   ├── lib/
│   │   │   ├── ws.ts            # WebSocket client with reconnect
│   │   │   ├── api.ts           # HTTP API client
│   │   │   ├── stores/          # Svelte 5 runes-based state
│   │   │   ├── components/      # Reusable UI components
│   │   │   └── theme/           # Catppuccin theme setup
│   │   ├── routes/
│   │   │   ├── +layout.svelte   # Root layout (header, tabs, FAB)
│   │   │   ├── overview/        # Overview tab
│   │   │   ├── players/         # Players tab
│   │   │   ├── tables/          # Tables tab
│   │   │   ├── financials/      # Financials tab
│   │   │   └── more/            # More tab (templates, settings)
│   │   └── app.html
│   ├── static/
│   │   └── sounds/              # Level change, break, bubble sounds
│   ├── svelte.config.js
│   ├── embed.go                 # //go:embed all:build
│   └── package.json
└── go.mod
```

### Pattern 1: Embedded NATS Server with JetStream

**What:** Start NATS server in-process with JetStream enabled and `sync_interval: always` for single-node durability.
**When to use:** Application startup in `cmd/leaf/main.go`.

```go
// Source: https://github.com/nats-io/nats-server/discussions/6242
import (
    "github.com/nats-io/nats-server/v2/server"
    "github.com/nats-io/nats.go"
)

func startEmbeddedNATS(dataDir string) (*server.Server, error) {
    opts := &server.Options{
        DontListen: true,  // In-process only, no TCP listener needed
        JetStream:  true,
        StoreDir:   dataDir,
        JetStreamMaxMemory:  64 * 1024 * 1024,  // 64MB memory limit
        JetStreamMaxStore:   1024 * 1024 * 1024, // 1GB disk limit
        JetStreamSyncInterval: 0, // 0 = "always" — fsync every write
    }

    ns, err := server.NewServer(opts)
    if err != nil {
        return nil, fmt.Errorf("failed to create NATS server: %w", err)
    }

    go ns.Start()

    if !ns.ReadyForConnections(5 * time.Second) {
        return nil, errors.New("NATS server startup timeout")
    }

    return ns, nil
}
```

**CRITICAL:** `sync_interval: always` (or `JetStreamSyncInterval: 0`) is mandatory. The Jepsen December 2025 analysis of NATS 2.12.1 found that the default 2-minute fsync interval means recently acknowledged writes exist only in memory and are lost on power failure. For single-node (non-replicated) deployments, every write must fsync immediately.

### Pattern 2: WebSocket Hub with Connection Registry

**What:** Central hub managing all WebSocket connections with topic-based broadcasting.
**When to use:** Real-time state updates to all connected operator/display clients.

```go
// Source: coder/websocket docs + standard hub pattern
import "github.com/coder/websocket"

type Hub struct {
    mu      sync.RWMutex
    clients map[*Client]struct{}
}

type Client struct {
    conn         *websocket.Conn
    tournamentID string // Subscribe to specific tournament
    send         chan []byte
}

func (h *Hub) Broadcast(tournamentID string, msg []byte) {
    h.mu.RLock()
    defer h.mu.RUnlock()
    for client := range h.clients {
        if client.tournamentID == tournamentID || client.tournamentID == "" {
            select {
            case client.send <- msg:
            default:
                // Client too slow, drop message
            }
        }
    }
}

// On new WebSocket connection — send full state snapshot
func (h *Hub) HandleConnect(w http.ResponseWriter, r *http.Request) {
    c, err := websocket.Accept(w, r, nil)
    if err != nil { return }

    client := &Client{conn: c, send: make(chan []byte, 256)}
    h.register(client)
    defer h.unregister(client)

    // Send full state snapshot on connect (CLOCK-09)
    snapshot := h.getCurrentState(client.tournamentID)
    client.send <- snapshot

    // Read/write pumps...
}
```

### Pattern 3: SvelteKit SPA Embedded in Go Binary

**What:** Build SvelteKit with adapter-static, embed the output, serve with SPA fallback.
**When to use:** Serving the frontend from the Go binary.

```javascript
// svelte.config.js
import adapter from '@sveltejs/adapter-static';

export default {
    kit: {
        adapter: adapter({
            pages: 'build',
            assets: 'build',
            fallback: 'index.html', // SPA fallback
            precompress: false,
            strict: true
        }),
        paths: {
            base: ''  // Served from root
        }
    }
};
```

```go
// frontend/embed.go
package frontend

import (
    "embed"
    "io/fs"
    "net/http"
    "strings"
)

//go:embed all:build
var files embed.FS

func Handler() http.Handler {
    fsys, _ := fs.Sub(files, "build")
    fileServer := http.FileServer(http.FS(fsys))

    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Try to serve static file first
        path := strings.TrimPrefix(r.URL.Path, "/")
        if path == "" {
            path = "index.html"
        }
        if _, err := fs.Stat(fsys, path); err != nil {
            // SPA fallback: serve index.html for client-side routing
            r.URL.Path = "/"
        }
        fileServer.ServeHTTP(w, r)
    })
}
```

### Pattern 4: Event-Sourced Audit Trail

**What:** Every state-changing action writes an immutable audit entry to both LibSQL and NATS JetStream.
**When to use:** All mutations (buy-in, bust-out, rebuy, clock pause, seat move, etc.).

```go
type AuditEntry struct {
    ID            string    `json:"id"`         // UUID
    TournamentID  string    `json:"tournament_id"`
    Timestamp     int64     `json:"timestamp"`  // UnixNano
    OperatorID    string    `json:"operator_id"`
    Action        string    `json:"action"`     // "player.bust", "financial.buyin", etc.
    TargetID      string    `json:"target_id"`  // Player/table/etc ID
    PreviousState json.RawMessage `json:"previous_state"`
    NewState      json.RawMessage `json:"new_state"`
    Metadata      json.RawMessage `json:"metadata,omitempty"`
    UndoneBy      *string   `json:"undone_by,omitempty"` // Points to undo entry
}

// Write to both LibSQL (persistence) and NATS JetStream (real-time broadcast)
func (a *AuditTrail) Record(ctx context.Context, entry AuditEntry) error {
    // 1. Insert into LibSQL audit table
    if err := a.store.InsertAudit(ctx, entry); err != nil {
        return err
    }
    // 2. Publish to NATS JetStream for real-time broadcast
    data, _ := json.Marshal(entry)
    _, err := a.js.Publish(ctx,
        fmt.Sprintf("tournament.%s.audit", entry.TournamentID),
        data,
    )
    return err
}
```

### Pattern 5: Int64 Financial Math

**What:** All monetary values stored and calculated as int64 cents. Never float64.
**When to use:** Every financial calculation (prize pool, payouts, rake, bounties).

```go
// All money is int64 cents. 1000 = $10.00 or 10.00 EUR or 1000 DKK (10 kr)
type Money int64

func (m Money) String() string {
    return fmt.Sprintf("%d.%02d", m/100, m%100)
}

// Prize pool: sum of all entry fees minus rake
func CalculatePrizePool(entries []Transaction) Money {
    var pool Money
    for _, e := range entries {
        pool += e.PrizeContribution // Already int64 cents
    }
    return pool
}

// Payout with round-down to venue denomination
func CalculatePayouts(pool Money, structure []PayoutTier, roundTo Money) []Money {
    payouts := make([]Money, len(structure))
    var distributed Money
    for i, tier := range structure {
        raw := Money(int64(pool) * int64(tier.BasisPoints) / 10000)
        payouts[i] = (raw / roundTo) * roundTo // Round down
        distributed += payouts[i]
    }
    // Remainder goes to 1st place (standard poker convention)
    payouts[0] += pool - distributed
    return payouts
}

// CI GATE TEST: sum of payouts must exactly equal prize pool
func TestPayoutSumEqualsPool(t *testing.T) {
    // ... property-based test across thousands of random inputs
    // assert: sum(payouts) == pool, always, zero deviation
}
```

### Anti-Patterns to Avoid

- **float64 for money:** Floating-point representation causes rounding errors. A pool of 10000 cents split 3 ways (3333 + 3333 + 3334) is exact in int64. With float64, 100.00/3 = 33.333... causes cumulative errors across a tournament.
- **Client-authoritative clock:** The clock MUST be server-authoritative. Client clocks drift, can be manipulated, and diverge across devices. Server sends ticks, clients display.
- **Mutable audit trail:** Audit entries must be append-only. "Undo" creates a NEW entry that references the original, never deletes or modifies existing entries.
- **Blocking WebSocket writes:** Never write to a WebSocket connection synchronously in the broadcast loop. Use buffered channels per client with drop semantics for slow consumers.
- **Global state instead of tournament-scoped:** Every piece of state (clock, players, tables, financials) must be scoped to a tournament ID. Global singletons break MULTI-01.

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Password hashing | Custom hash function | golang.org/x/crypto/bcrypt | Bcrypt handles salt generation, timing-safe comparison, configurable cost |
| JWT token management | Custom token format | golang-jwt/jwt/v5 | Standard claims, expiry, signing algorithm negotiation |
| QR code generation | Manual QR encoding | skip2/go-qrcode | Reed-Solomon error correction, multiple output formats |
| WebSocket protocol | Raw TCP upgrade | coder/websocket | RFC 6455 compliance, compression, ping/pong, close handshake |
| SQLite FTS | Custom search index | FTS5 (built into LibSQL) | Tokenization, ranking, prefix queries, diacritics handled |
| UUID generation | Custom ID scheme | google/uuid | RFC 4122 compliant, v4 random, v7 time-ordered |
| Theme colors | Manual hex values | @catppuccin/palette | 26 colors across 4 flavors, community-maintained, consistent |
| HTTP routing + middleware | Custom mux | go-chi/chi v5 | Middleware composition, route grouping, stdlib compatible |

**Key insight:** The complexity in this phase is in the poker domain logic (ICM, balancing, blind wizard, PKO chains), not in infrastructure. Use battle-tested libraries for all infrastructure concerns so implementation time is spent on domain logic.

## Common Pitfalls

### Pitfall 1: NATS JetStream Default sync_interval Loses Data

**What goes wrong:** Acknowledged writes exist only in OS page cache for up to 2 minutes. Power failure loses all recent tournament state.
**Why it happens:** NATS defaults to `sync_interval: 2m` for performance, relying on cluster replication for durability. Single-node deployments have no replication.
**How to avoid:** Set `sync_interval: always` (or `JetStreamSyncInterval: 0` in Go opts) on every embedded NATS instance. Accept the ~10-20% write throughput reduction.
**Warning signs:** Tests pass because no simulated power failure; first real power cut at a venue loses the last 2 minutes of tournament data.

### Pitfall 2: go-libsql Unpinned Dependency Breaks Build

**What goes wrong:** `go get github.com/tursodatabase/go-libsql@latest` resolves to a different commit on different days. Breaking changes arrive silently.
**Why it happens:** go-libsql has no tagged releases. Go modules fall back to pseudo-versions based on commit hash.
**How to avoid:** Pin to a specific commit hash in go.mod. Test thoroughly before updating. Document the pinned commit with a comment.
**Warning signs:** CI builds succeed locally but fail in a clean environment, or vice versa.

### Pitfall 3: ICM Calculation Factorial Explosion

**What goes wrong:** Exact Malmuth-Harville ICM calculation for 20+ players takes minutes or hours. UI freezes during chop negotiation.
**Why it happens:** ICM exhausts all possible finish permutations. For N players this is O(N!) — 15 players = 1.3 trillion permutations.
**How to avoid:** Use exact calculation for <= 10 players. Use Monte Carlo sampling (Tysen Streib method, 2011) for 11+ players with 100K iterations — converges to <0.1% error in under 1 second.
**Warning signs:** Chop calculation works in testing (4-5 players) but hangs in production with 8+ players.

### Pitfall 4: Payout Rounding Creates Money from Nothing

**What goes wrong:** Prize pool is 10000 cents, payouts sum to 10050 cents due to rounding up. Venue pays out more than collected.
**Why it happens:** Rounding each payout independently can round up. Multiple round-ups accumulate.
**How to avoid:** Always round DOWN to venue denomination. Assign remainder to 1st place. CI gate test: assert `sum(payouts) == prize_pool` for every possible input combination.
**Warning signs:** Payout sum doesn't match prize pool in edge cases (odd numbers, large fields, unusual denominations).

### Pitfall 5: Clock Drift Between Server and Client

**What goes wrong:** Timer shows different values on different devices. Operator's phone says 45 seconds, display says 43 seconds.
**Why it happens:** Client-side timers using `setInterval` drift due to JS event loop scheduling, tab throttling, and device sleep.
**How to avoid:** Server is authoritative. Send absolute state (level, remaining_ms, is_paused, server_timestamp) not relative ticks. Client calculates display from server time, correcting for known RTT. Re-sync on every WebSocket message.
**Warning signs:** Devices show slightly different times; discrepancy grows over long levels.

### Pitfall 6: Undo Doesn't Re-Rank Correctly

**What goes wrong:** Undoing a bust-out puts the player back but rankings are wrong. Players who busted after them have incorrect positions.
**Why it happens:** Rankings are calculated at bust time. Undoing a bust requires recalculating ALL rankings from that point forward.
**How to avoid:** Rankings should be derived from the ordered bust-out list, not stored as independent values. Undo removes from bust list, all subsequent positions shift. Re-derive, don't patch.
**Warning signs:** Rankings look correct for simple undo (last bust) but break for earlier undos.

### Pitfall 7: Table Balancing Race Condition

**What goes wrong:** System suggests "move Player A from Table 1 to Table 4". Before TD executes, Player B busts from Table 1. Now the move makes tables unbalanced in the other direction.
**Why it happens:** Time gap between suggestion and execution. Real tournaments have concurrent busts during hands in play.
**How to avoid:** The CONTEXT.md already addresses this: "Suggestion is live and adaptive — if Table 1 loses a player before the move happens, system recalculates or cancels." Implement suggestions as pending proposals that are re-validated before execution.
**Warning signs:** TD executes a stale balancing suggestion and tables end up worse than before.

### Pitfall 8: SvelteKit adapter-static Path Resolution

**What goes wrong:** Routes work in development but return 404 in production when embedded in Go binary.
**Why it happens:** SvelteKit adapter-static generates files like `build/players/index.html`. The Go file server doesn't automatically resolve `/players` to `/players/index.html`.
**How to avoid:** Configure `fallback: 'index.html'` in adapter-static config for SPA mode. The Go handler falls back to index.html for any path not found as a static file, letting SvelteKit's client-side router handle navigation.
**Warning signs:** Direct navigation to routes works, but refresh on a nested route returns 404.

## Code Examples

### LibSQL Local Database Setup

```go
// Source: https://github.com/tursodatabase/go-libsql/blob/main/example/local/main.go
import (
    "database/sql"
    _ "github.com/tursodatabase/go-libsql"
)

func openDB(dataDir string) (*sql.DB, error) {
    dbPath := filepath.Join(dataDir, "felt.db")
    db, err := sql.Open("libsql", "file:"+dbPath)
    if err != nil {
        return nil, fmt.Errorf("open libsql: %w", err)
    }

    // Enable WAL mode for concurrent reads during writes
    if _, err := db.Exec("PRAGMA journal_mode=WAL"); err != nil {
        return nil, err
    }
    // Enable foreign keys
    if _, err := db.Exec("PRAGMA foreign_keys=ON"); err != nil {
        return nil, err
    }

    return db, nil
}
```

### Clock Engine State Machine

```go
type ClockState int
const (
    ClockStopped ClockState = iota
    ClockRunning
    ClockPaused
)

type ClockEngine struct {
    mu            sync.RWMutex
    tournamentID  string
    state         ClockState
    levels        []Level
    currentLevel  int
    remainingNs   int64       // Nanoseconds remaining in current level
    lastTick      time.Time   // Monotonic clock reference
    totalElapsed  time.Duration
    warnings      []WarningThreshold
    hub           *ws.Hub
}

func (c *ClockEngine) Tick() {
    c.mu.Lock()
    defer c.mu.Unlock()

    if c.state != ClockRunning { return }

    now := time.Now()
    elapsed := now.Sub(c.lastTick)
    c.lastTick = now
    c.remainingNs -= elapsed.Nanoseconds()
    c.totalElapsed += elapsed

    // Check for level transition
    if c.remainingNs <= 0 {
        c.advanceLevel()
    }

    // Check warning thresholds
    c.checkWarnings()

    // Determine tick rate: 10/sec in final 10s, 1/sec otherwise
    remainingSec := c.remainingNs / int64(time.Second)
    msg := c.buildStateMessage()

    // Broadcast to all clients
    c.hub.Broadcast(c.tournamentID, msg)
}

func (c *ClockEngine) Snapshot() ClockSnapshot {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return ClockSnapshot{
        TournamentID:  c.tournamentID,
        State:         c.state,
        CurrentLevel:  c.currentLevel,
        Level:         c.levels[c.currentLevel],
        RemainingMs:   c.remainingNs / int64(time.Millisecond),
        TotalElapsed:  c.totalElapsed,
        ServerTime:    time.Now().UnixMilli(),
    }
}
```

### Catppuccin Mocha Theme Setup

```css
/* Source: https://catppuccin.com/palette/ — Mocha flavor */
:root {
    /* Base */
    --ctp-base: #1e1e2e;
    --ctp-mantle: #181825;
    --ctp-crust: #11111b;

    /* Text */
    --ctp-text: #cdd6f4;
    --ctp-subtext1: #bac2de;
    --ctp-subtext0: #a6adc8;

    /* Surface */
    --ctp-surface2: #585b70;
    --ctp-surface1: #45475a;
    --ctp-surface0: #313244;

    /* Overlay */
    --ctp-overlay2: #9399b2;
    --ctp-overlay1: #7f849c;
    --ctp-overlay0: #6c7086;

    /* Accents */
    --ctp-rosewater: #f5e0dc;
    --ctp-flamingo: #f2cdcd;
    --ctp-pink: #f5c2e7;
    --ctp-mauve: #cba6f7;
    --ctp-red: #f38ba8;
    --ctp-maroon: #eba0ac;
    --ctp-peach: #fab387;
    --ctp-yellow: #f9e2af;
    --ctp-green: #a6e3a1;
    --ctp-teal: #94e2d5;
    --ctp-sky: #89dceb;
    --ctp-sapphire: #74c7ec;
    --ctp-blue: #89b4fa;
    --ctp-lavender: #b4befe;
}

body {
    background-color: var(--ctp-base);
    color: var(--ctp-text);
    font-family: system-ui, -apple-system, sans-serif;
}
```

### Svelte 5 Runes WebSocket State

```typescript
// Source: Svelte 5 runes documentation
// lib/stores/tournament.svelte.ts

class TournamentState {
    clock = $state<ClockSnapshot | null>(null);
    players = $state<Player[]>([]);
    tables = $state<Table[]>([]);
    financials = $state<FinancialSummary | null>(null);
    activity = $state<ActivityEntry[]>([]);

    get remainingPlayers() {
        return this.players.filter(p => p.status === 'active').length;
    }

    get isBalanced() {
        if (this.tables.length <= 1) return true;
        const counts = this.tables.map(t => t.players.length);
        return Math.max(...counts) - Math.min(...counts) <= 1;
    }

    handleMessage(msg: WSMessage) {
        switch (msg.type) {
            case 'clock.tick':
                this.clock = msg.data;
                break;
            case 'player.update':
                // Reactive update via $state
                const idx = this.players.findIndex(p => p.id === msg.data.id);
                if (idx >= 0) this.players[idx] = msg.data;
                break;
            // ... other message types
        }
    }
}

export const tournament = new TournamentState();
```

### PIN Authentication Flow

```go
// PIN login -> bcrypt verify -> JWT issue
func (a *AuthService) Login(ctx context.Context, pin string) (string, error) {
    // Rate limiting: exponential backoff after 5 failures
    if blocked := a.rateLimiter.Check(pin); blocked {
        return "", ErrTooManyAttempts
    }

    operators, err := a.store.GetOperators(ctx)
    if err != nil { return "", err }

    for _, op := range operators {
        if err := bcrypt.CompareHashAndPassword([]byte(op.PINHash), []byte(pin)); err == nil {
            // Match found — issue JWT
            token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
                "sub":  op.ID,
                "role": op.Role, // "admin", "floor", "viewer"
                "iat":  time.Now().Unix(),
                "exp":  time.Now().Add(24 * time.Hour).Unix(),
            })
            return token.SignedString(a.signingKey)
        }
    }

    a.rateLimiter.RecordFailure(pin)
    return "", ErrInvalidPIN
}
```

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Svelte stores (writable/readable) | Svelte 5 runes ($state, $derived, $effect) | Oct 2024 (Svelte 5.0) | All state management uses runes, stores deprecated for new code |
| nats.JetStreamContext (legacy API) | nats.go/jetstream package (new API) | 2024 | Simpler interfaces, pull consumers, better stream management |
| gorilla/websocket | coder/websocket (nhooyr fork) | 2024 | Coder maintains the project, context.Context support, concurrent writes |
| Go 1.21 stdlib ServeMux | Go 1.22+ enhanced ServeMux | Feb 2024 | Method matching + path params in stdlib, but chi still better for middleware |
| Manual ICM calculation | Monte Carlo ICM approximation | 2011 (Streib) | Practical ICM for any field size, converges quickly |

**Deprecated/outdated:**
- **Svelte stores for new code:** Still work but Svelte 5 docs recommend runes ($state) for all new code. Stores remain for backward compatibility.
- **nats.JetStreamContext:** Legacy API. The `jetstream` package under `nats.go/jetstream` is the replacement. Don't use the old JetStreamContext methods.
- **gorilla/websocket as default choice:** Still works but archived/maintenance-mode. coder/websocket is the actively maintained modern alternative.

## Open Questions

1. **go-libsql CGO Cross-Compilation for CI**
   - What we know: go-libsql requires CGO_ENABLED=1 and precompiled libsql for linux/amd64
   - What's unclear: Whether CI runners (GitHub Actions) have the right C toolchain pre-installed, or if we need a custom Docker build image
   - Recommendation: Test early with a minimal CI pipeline. If problematic, use a Debian-based CI image with build-essential.

2. **go-libsql Exact Commit to Pin**
   - What we know: No tagged releases. Must pin to commit hash.
   - What's unclear: Which commit is most stable as of March 2026
   - Recommendation: Check the repo's main branch, pick the latest commit, verify it passes local tests, pin it with a comment in go.mod.

3. **NATS JetStream Stream Configuration for Audit Trail**
   - What we know: JetStream streams need proper retention, limits, and subject patterns
   - What's unclear: Optimal retention policy (limits vs interest), max message size for audit entries with full state snapshots, disk space planning
   - Recommendation: Start with limits-based retention (MaxAge: 90 days, MaxBytes: 1GB), adjust based on real tournament data sizes.

4. **Svelte 5 Runes with SvelteKit adapter-static**
   - What we know: Svelte 5 runes work for state management, adapter-static produces a SPA
   - What's unclear: Whether $state runes in .svelte.ts files work correctly with adapter-static's prerendering (runes are runtime, prerendering is build-time)
   - Recommendation: Use `fallback: 'index.html'` SPA mode to avoid prerendering issues. Runes are client-side only.

5. **Thermal Printer Receipt Integration**
   - What we know: FIN-13 requires receipt generation, CONTEXT.md mentions configurable receipt settings
   - What's unclear: Which thermal printer protocol to target (ESC/POS is standard), whether to generate in Go or browser
   - Recommendation: Generate receipt as HTML/CSS rendered in a hidden iframe for print. Thermal printer support can use ESC/POS in a later iteration. Digital receipts first.

## Sources

### Primary (HIGH confidence)

- [go-libsql GitHub](https://github.com/tursodatabase/go-libsql) — Local-only API (`sql.Open("libsql", "file:"+path)`), CGO requirement, platform support
- [go-libsql local example](https://github.com/tursodatabase/go-libsql/blob/main/example/local/main.go) — Verified local-only database opening pattern
- [NATS JetStream docs](https://docs.nats.io/nats-concepts/jetstream) — JetStream configuration, sync_interval
- [NATS server discussions #6242](https://github.com/nats-io/nats-server/discussions/6242) — Embedded JetStream account setup, PR #6261 fix
- [Jepsen NATS 2.12.1](https://jepsen.io/analyses/nats-2.12.1) — sync_interval durability finding, single-node recommendation
- [coder/websocket GitHub](https://github.com/coder/websocket) — v1.8.14, API, features
- [go-chi/chi GitHub](https://github.com/go-chi/chi) — v5.2.5, middleware, routing
- [golang-jwt/jwt v5](https://pkg.go.dev/github.com/golang-jwt/jwt/v5) — JWT library API
- [Catppuccin palette](https://catppuccin.com/palette/) — Mocha hex values verified
- [SvelteKit adapter-static docs](https://svelte.dev/docs/kit/adapter-static) — Configuration, fallback, prerender
- [Svelte 5 runes blog](https://svelte.dev/blog/runes) — $state, $derived, $effect API
- [ICM Wikipedia](https://en.wikipedia.org/wiki/Independent_Chip_Model) — Malmuth-Harville algorithm, factorial complexity

### Secondary (MEDIUM confidence)

- [Liip blog: Embed SvelteKit into Go](https://www.liip.ch/en/blog/embed-sveltekit-into-a-go-binary) — Complete go:embed + adapter-static pattern, verified with official docs
- [Replay Poker table rebalancing](https://replayhelp.casino.org/hc/en-us/articles/360001878254-How-table-rebalancing-works) — TDA-compliant balancing algorithm description
- [PokerSoup blind calculator](https://pokersoup.com/tool/blindStructureCalculator) — Blind structure wizard algorithm approach
- [Poker TDA 2024 rules](https://www.pokertda.com/poker-tda-rules/) — Official TDA breaking/balancing rules
- [GTO Wizard PKO theory](https://blog.gtowizard.com/the-theory-of-progressive-knockout-tournaments/) — PKO bounty mechanics (half-split)
- [HoldemResources ICM](https://www.holdemresources.net/blog/high-accuracy-mtt-icm/) — Monte Carlo ICM approximation for large fields

### Tertiary (LOW confidence)

- [nats-server releases](https://github.com/nats-io/nats-server/releases) — v2.12.4 latest stable (Jan 2026), needs re-check at implementation time
- go-libsql latest commit hash — needs to be fetched fresh at implementation time
- Svelte exact version — reported as 5.46+ (Jan 2026), may have newer patches

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — All core libraries verified via official GitHub repos, official docs, and package registries
- Architecture: HIGH — Patterns (go:embed SPA, embedded NATS, WebSocket hub, event sourcing) verified via multiple official examples and production usage
- Pitfalls: HIGH — NATS Jepsen finding verified via official Jepsen report; ICM complexity verified via Wikipedia and academic sources; other pitfalls derived from verified library characteristics
- Domain logic: MEDIUM — Poker domain (ICM, balancing, blind wizard) based on community sources and TDA rules, not on verified software implementations in Go

**Research date:** 2026-03-01
**Valid until:** 2026-03-31 (30 days — stack is stable, check go-libsql for new tagged releases)