pvm/docs/VISION.md

PVM - Poker Venue Manager: Vision

Overview

PVM is a comprehensive SaaS platform for managing poker venues, tournaments, cash games, and the people who make them happen. It is designed to be the single system of record for poker venue operations — from the first shuffle to the final hand.

Core Philosophy

• Always On: Venues cannot afford downtime. PVM supports optional local nodes (e.g. Raspberry Pi 5) that act as on-premise proxies, keeping the venue fully operational during internet outages and syncing back to the cloud in near-realtime when connectivity is restored.
• Player-Centric: A single PVM account follows a player across every venue they visit. Public venues can be browsed and joined freely; private venues operate on an invite-only basis.
• Operator-First UX: Venue managers, floor staff, and dealers get purpose-built interfaces — not repurposed admin panels.

---

System Architecture at a Glance

                        ┌──────────────────────┐
                        │   PVM Cloud (SaaS)    │
                        │  ┌────────────────┐   │
                        │  │  Central API    │   │
                        │  │  + Database     │   │
                        │  │  + Messaging    │   │
                        │  └────────────────┘   │
                        └──────────┬───────────┘
                                   │
                     near-realtime sync
                                   │
            ┌──────────────────────┼──────────────────────┐
            │                      │                      │
   ┌────────▼────────┐   ┌────────▼────────┐   ┌────────▼────────┐
   │  Venue Node A   │   │  Venue Node B   │   │  Cloud-Only     │
   │  (RPi5 / local) │   │  (RPi5 / local) │   │  Venue C        │
   │  Local proxy +  │   │  Local proxy +  │   │  (no local node)│
   │  offline cache  │   │  offline cache  │   │                 │
   └─────────────────┘   └─────────────────┘   └─────────────────┘

Multi-tenant SaaS: One customer (operator) can manage one or more venues. Each venue optionally runs a local node for resilience.

---

Feature Domains

1. Tournament Management

• Planning & Scheduling: Create one-off or recurring tournament series with full structure editors (levels, blinds, antes, breaks).
• Live Tournament Clock: Real-time clock with level progression, break timers, prize pool calculations, and average stack displays.
• Seating & Table Management: Automated random seating, table balancing, and break/merge logic.
• Registration: Pre-registration, late registration windows, re-entries, and add-ons.
• Results & Leaderboards: Automatic payout calculation, result history, and season-long leaderboard tracking.

2. Cash Game Management

• Game Types & Stakes: Configure any game type (NLH, PLO, mixed games, etc.) with custom stake levels.
• Table Tracking: Open/close tables, track active seats, buy-ins, and session durations.
• Waiting Lists: Smart waiting lists with player notifications, priority rules, and seat-change requests.
• Session History: Full session logging per player for analytics and credit management.

3. Player Accounts

• Universal PVM Account: Players sign up for PVM first, then join venues. One account, all venues. Player profile, game history, and preferences travel with the player.
• Venue Discovery: Browse public venues, view upcoming events, and join with a tap.
• Private Venues: Invite-only access with approval workflows.
• Membership Management: Venue-specific membership tiers with benefits, dues tracking, and renewal automation.
• Line of Credit: Configurable credit lines for approved players with tracking and limits. PVM tracks records only — venues handle actual money via their own POS systems.

4. Dealer Management

• Dealer Profiles: Dealers maintain their own PVM profiles with certifications, game proficiencies, and availability.
• Availability & Scheduling: Dealers mark themselves available via the mobile app/webapp. A calendar interface lets them manage their schedule across multiple venues.
• Shift Management: Venue managers assign dealers to tables/tournaments. Dealers can request shift swaps with configurable approval workflows (auto-approve, manager approval, etc.).
• Cross-Venue Mobility: Dealers are not tied to a single venue — they work where the action is. PVM makes this seamless.

5. Venue Display System

• Android Display Client: A lightweight Android app (or $40 4K Android box) auto-discovers the local node via mDNS, registers with a unique device ID, and renders whatever the system assigns it. Falls back to cloud SaaS if the local node is offline.
• Screen Manager: A dashboard to assign display destinations and select what each screen shows. Group screens by area (tournament room, cash room, lobby).
• Display Content:
  • Tournament live clock
  • Current seating charts
  • Waiting lists
  • Cash game availability
  • Custom announcements & information slideshows
  • Leaderboards and results

6. Venue Operations

• Multi-Venue Dashboard: Operators with multiple venues get a unified overview.
• Floor Management: Real-time floor view — see every table, every game, every seat.
• Reporting & Analytics: Revenue tracking, player activity, dealer hours, game popularity, and more.
• Notifications & Alerts: Push notifications for players (seat available, tournament starting), dealers (shift assigned, swap request), and managers (table needs attention, credit limit approaching).

---

Local Node Architecture

For venues that subscribe to the local node option:

• Hardware: Raspberry Pi 5 (or equivalent small-form-factor device).
• Runtime: Docker on stock Raspberry Pi OS. Two containers: PVM node (Rust binary with embedded libSQL) + NATS leaf node.
• Role: Acts as a local proxy and offline cache. All venue operations can continue uninterrupted during internet outages for up to 72 hours.
• Sync Strategy: Event-based sync via NATS JetStream. All mutations become events that are replayed to build state. When offline, events are buffered locally and replayed on reconnect.
• Connectivity: WireGuard tunnel to the Hetzner cloud server. NATS leaf node connects to the cloud NATS cluster.
• Security: The local node authenticates with the cloud via WireGuard + TLS. Local data is encrypted at rest.
• Management: Nodes are provisioned via a one-liner curl script. Updates are Docker image pulls.

---

Client Applications

Platform	Type	Primary Users
Web (Desktop)	SvelteKit SPA / PWA	Venue managers, floor staff, operators
Web (Mobile)	Responsive PWA (Capacitor later)	Players, dealers
Venue Displays	Android display client app	TVs throughout the venue
Local Node UI	Lightweight admin panel	On-site tech / venue manager

---

Design Principles

1. Offline-First Where It Matters: The local node ensures venue operations never stop. Cloud-only venues degrade gracefully with clear user feedback.
2. Real-Time by Default: Tournament clocks, waiting lists, seat availability, and notifications are all live. No polling, no stale data.
3. Security Without Friction: Player accounts and credit tracking demand strong security. But the UX should never feel like a bank app — it should feel like a poker app. PVM does not handle actual money — venues manage that via their own POS systems.
4. Multi-Tenancy Done Right: Strict data isolation between operators/venues. Shared player profiles are read-only across venue boundaries unless the player opts in.
5. Extensibility: The system should be built with a clean API layer so that future integrations (payment processors, poker room rating sites, streaming platforms) are straightforward.

---

Target Users

• Venue Operators / Owners: The paying customer. They need oversight, reporting, and control.
• Floor Managers / Tournament Directors: The power users. They need speed, reliability, and a UI that keeps up with a busy poker room.
• Dealers: They need scheduling, availability management, and shift coordination — ideally from their phone.
• Players: They need to find games, register for tournaments, check their history, and manage their account.

---

This document represents the full vision. Implementation will be phased, with the core tournament and cash game management forming the foundation.