From f0d2f1687715724abc43d52821726eee3b8b73a2 Mon Sep 17 00:00:00 2001 From: Mikkel Georgsen Date: Sat, 28 Feb 2026 15:47:28 +0100 Subject: [PATCH] docs: initialize project --- .planning/PROJECT.md | 130 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 .planning/PROJECT.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..51ceb73 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,130 @@ +# 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*