# Felt — The Operating System for Poker Venues

## What This Is

Felt is an all-in-one poker venue operating system built on a resilient edge-cloud architecture. An ARM64 SBC "Leaf Node" runs the venue autonomously with NVMe storage. Ultra-cheap wireless display nodes replace HDMI cables. Players interact via their phones (PWA). A cloud Core layer handles cross-venue leagues, player profiles, public scheduling, and remote access. Everything flows through a self-hosted Netbird WireGuard mesh — network agnostic, zero-config, encrypted end-to-end.

The product targets poker venues of all sizes — from a 3-table Copenhagen bar to a 40-table casino floor — replacing fragmented tools (TDD, whiteboards, spreadsheets, Blind Valet, BravoPokerLive) with one integrated platform.

## Core Value

A venue can run a complete tournament offline on a €100 device with wireless displays and player mobile access — and it just works, on any network, with zero IT involvement.

## Requirements

### Validated

(None yet — ship to validate)

### Active

**Phase 1 (Development Focus): Live Tournament Management**
- [ ] Full tournament clock engine (countdown, blinds, antes, levels, breaks, chip-ups, pause/resume)
- [ ] Financial engine (buy-ins, rebuys, add-ons, bounties, payouts, prize pool calculation, rake)
- [ ] Player management (database, registration, bust-out tracking, chip counts, action history)
- [ ] Table & seating (configurable layouts, random seating, auto-balancing, table breaks, drag-and-drop moves)
- [ ] Multi-tournament support (run multiple tournaments simultaneously)
- [ ] League & season management (configurable point formulas, standings, archives)
- [ ] Wireless display system (node registry, view assignment, tournament clock/rankings/seating/schedule views)
- [ ] Digital signage (info screens, event promos, drink specials, sponsor ads, playlists, auto-scheduling)
- [ ] WYSIWYG content editor with AI assist (template gallery, AI-generated promo cards/imagery, venue branding)
- [ ] Player mobile PWA (QR code access, live clock, blinds, rankings, personal stats, league standings)
- [ ] Player access via Netbird reverse proxy (public HTTPS → WireGuard → Leaf, same URL from anywhere)
- [ ] Events engine (triggers, conditions, actions — sounds, messages, view changes, webhooks)
- [ ] Export (CSV, JSON, HTML)
- [ ] NATS-based sync (Leaf → Core, queued offline, replayed on reconnect)
- [ ] Operator UI (mobile-first, touch-native, dark-room ready, TDD-depth with modern UX)
- [ ] Authentication (PIN login offline, OIDC via Authentik when online, operator roles)
- [ ] TDD data import (blind structures, player database, tournament history, leagues)

**Phase 2 (Development Focus): Cash Game Operations**
- [ ] Waitlist management (by game type and stakes, display integration, notifications)
- [ ] Table management (open/close, game types, stakes, seat tracking, status board)
- [ ] Game type registry (all poker variants, configurable stakes, betting structures)
- [ ] Session tracking (player sessions, buy-in/cashout, duration, history)
- [ ] Rake tracking (percentage/time/flat, per-table reporting, financial analytics)
- [ ] Must-move tables (automated progression, main game priority)
- [ ] Seat change requests (queue tracking, notification on availability)
- [ ] Table transfers (cross-table moves within sessions)
- [ ] Player alerts (waitlist position, seat available, preferred game opened)

**Phase 3 (Development Focus): Complete Venue Platform**
- [ ] Dealer management (scheduling, skill profiles, shift trading, clock-in/out, rotation)
- [ ] Player loyalty system (points engine, tier system, rewards catalog, automated promos)
- [ ] Private venues & memberships (privacy modes, invite codes, member tiers, guest system)
- [ ] Venue analytics & reporting (revenue dashboards, player analytics, operational analytics)
- [ ] Public venue presence (venue profile page, online event registration, schedule publishing)

**Phase 4 (Development Focus): Native Apps & Platform Maturity**
- [ ] Native player app (iOS + Android — push notifications, Wallet integration, social features)
- [ ] Native venue management app (iOS + Android — push alerts, biometric auth, background sync)
- [ ] Social features (private groups, activity feed, achievements, friend-based venue discovery)

### Out of Scope

- Online poker / real-money gambling — Felt is a management tool, not a gambling platform
- Payment processing — tracks amounts, doesn't process transactions
- Video streaming / live poker broadcast — not in the product vision
- BYO hardware — Felt ships pre-configured, locked-down devices only
- Third-party cloud dependencies (Cloudflare, AWS, etc.) — self-hosted everything

## Context

**Technical Environment:**
- Leaf Node: ARM64 SBC (Orange Pi 5 Plus reference board, ~€100) with NVMe storage
- Display Node: Raspberry Pi Zero 2 W (~€20) running Chromium kiosk
- Core: Hetzner dedicated server running Proxmox VE with LXC containers
- Backend: Go (shared codebase for Leaf and Core, different builds)
- Frontend: SvelteKit (operator UI, player PWA, admin dashboard)
- Database: LibSQL on Leaf (embedded SQLite), PostgreSQL on Core
- Message Queue: NATS JetStream (embedded on Leaf, clustered on Core)
- Identity: Authentik (self-hosted OIDC IdP)
- Networking: Netbird (WireGuard mesh, reverse proxy, DNS, SSH, firewall policies)

**Design Philosophy:** "TDD's brain, Linear's face." — Match The Tournament Director's depth and power while looking and feeling like a modern premium product. Dark-room ready, touch-native, glanceable, information-dense without clutter.

**Color System:** Catppuccin Mocha-based dark theme (default), with Catppuccin Latte light alternative. Typography: Inter (UI) + JetBrains Mono (data/timers). Poker-specific accents (felt green, card white, bounty pink, prize yellow).

**Competition:**
- The Tournament Director (TDD): Feature-rich but Windows-only, 2002-era UI, no mobile/cloud/wireless
- Blind Valet: Simple cloud timer, dead without internet
- Poker Atlas: Discovery only, zero operational tooling
- BravoPokerLive: US waitlist app, no tournaments, no displays

**Business Model:**
- Free tier: Full tournament engine on virtual Leaf in cloud (requires internet)
- Offline tier (€25/mo): Dedicated Leaf + display nodes + offline operation
- Pro tier (€100/mo): Everything + cash games + dealers + loyalty + analytics
- Casino tiers (€249-999+/mo): Multi-room, cross-property, enterprise features

**User's Development Phases vs. GSD Planning Phases:**
The user's spec describes 4 product development phases (Tournament → Cash Games → Full Venue → Native Apps). These are the user's product focus areas, not to be confused with GSD's planning phases which break down the work within those development phases.

## Constraints

- **Hardware:** Must run on ARM64 SBC with 4GB+ RAM, NVMe storage. Display nodes on Pi Zero 2 W (512MB RAM)
- **Offline-first:** Entire tournament operation must work without internet. Cloud is never a dependency during operation
- **Network agnostic:** Must work on any internet connection via Netbird WireGuard mesh. No firewall config, no port forwarding
- **Self-hosted:** No third-party MITM. Self-hosted Netbird, Authentik, Core. Full stack ownership
- **Security:** LUKS encryption at rest, WireGuard in transit, RLS multi-tenancy, GDPR compliance, audit trail on all state changes
- **Performance:** State changes propagate to all clients within 100ms via WebSocket. Display views readable from 10+ feet
- **Solo developer initially:** Architecture must be manageable for a single developer to build and maintain

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Go for backend (Leaf + Core) | Single binary, ARM cross-compile, goroutine concurrency, excellent stdlib | — Pending |
| SvelteKit for all frontends | Shared codebase, PWA support, SSR for public pages, SPA for operator | — Pending |
| LibSQL over plain SQLite on Leaf | SQLite-compatible with replication support, better concurrent writes | — Pending |
| NATS JetStream for sync | Runs on Pi (~10MB RAM), persistent queuing, survives offline, ordered replay | — Pending |
| Netbird as infrastructure backbone | WireGuard mesh + reverse proxy + DNS + SSH + firewall in one self-hosted platform | — Pending |
| Authentik as IdP | Self-hosted, OIDC for Netbird + Felt, lightweight (~200MB RAM), Apache 2.0 | — Pending |
| Catppuccin Mocha color system | Dark-room optimized, established palette, systematic accent colors | — Pending |
| Platform-level player identity | Players belong to Felt, not venues — creates network effects and platform lock-in | — Pending |
| No BYO hardware | Security, reliability, support consistency, controlled full chain | — Pending |
| Free tier with virtual Leaf | Full tournament engine for free, costs ~€0.45/mo per venue, drives adoption flywheel | — Pending |
| Proxmox VE for Core hosting | LXC + KVM, web management, PBS backup integration, scales by adding nodes | — Pending |

---
*Last updated: 2026-02-28 after initialization*