From 7bd1805b678f7e2b11918e54bd384413820ebfd4 Mon Sep 17 00:00:00 2001 From: Mikkel Georgsen Date: Sun, 8 Feb 2026 02:39:17 +0100 Subject: [PATCH] Initial commit: project vision and README Establish PVM (Poker Venue Manager) project with product vision document covering all feature domains and a clean README with project overview. Co-Authored-By: Claude Opus 4.6 --- README.md | 49 +++++++++++++++++ docs/VISION.md | 139 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 188 insertions(+) create mode 100644 README.md create mode 100644 docs/VISION.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5d6338d --- /dev/null +++ b/README.md @@ -0,0 +1,49 @@ +

+ PVM Logo +

+ +

PVM

+

Poker Venue Manager

+ +

+ The all-in-one platform for poker venue operations.
+ Tournaments. Cash games. Dealers. Players. Displays. All managed. Always on. +

+ +

+ SaaS · Offline-Capable · Real-Time · Multi-Venue +

+ +--- + +## What is PVM? + +PVM is a comprehensive management system for poker venues of any size. It handles the full lifecycle of venue operations: + +- **Tournament Management** — Planning, live clocks, seating, registration, results, and recurring series +- **Cash Game Operations** — Table tracking, waiting lists, game types, and session history +- **Player Accounts** — One account across all venues, memberships, credit lines, and game history +- **Dealer Coordination** — Scheduling, availability, shift swaps, and cross-venue mobility +- **Display Streaming** — Push live clocks, seatings, and info to Chromecast screens throughout the venue +- **Local Node Support** — Optional on-premise Raspberry Pi 5 proxy for zero-downtime operation during internet outages + +## Architecture + +``` + PVM Cloud (SaaS) ◄── near-realtime sync ──► Venue Local Nodes (RPi5) + │ + ├── Web App (managers, staff, players, dealers) + ├── Mobile PWA / Native App (players, dealers) + └── Chromecast Receiver (venue display screens) +``` + +## Documentation + +- **[Vision & Feature Overview](docs/VISION.md)** — The full product vision and feature roadmap +- **Tech Stack** — *Coming soon* — Research and decisions on the technology foundation + +--- + +

+ Built for the poker community. +

diff --git a/docs/VISION.md b/docs/VISION.md new file mode 100644 index 0000000..bf883e0 --- /dev/null +++ b/docs/VISION.md @@ -0,0 +1,139 @@ +# 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**: 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, limits, and settlement workflows. + +### 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. Screen & Display Management + +- **Chromecast Integration**: Stream live content to any number of Chromecast devices on the local network. +- **Screen Manager**: A dashboard to assign Chromecast destinations and select what each screen displays. +- **Stream Types**: + - Tournament live clock + - Current seating charts + - Waiting lists + - Cash game availability + - Custom announcements & information slides + - 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). +- **Role**: Acts as a local proxy and offline cache. All venue operations can continue uninterrupted during internet outages. +- **Sync Strategy**: Near-realtime bidirectional sync with the PVM cloud when connectivity is healthy. Conflict resolution follows a last-write-wins strategy with domain-specific merge rules where needed (e.g. tournament state machines are authoritative from the node during a live event). +- **Security**: The local node authenticates with the cloud via mutual TLS. Local data is encrypted at rest. +- **Management**: Nodes are remotely provisioned and updated from the PVM cloud admin. + +--- + +## Client Applications + +| Platform | Type | Primary Users | +|----------|------|---------------| +| Web (Desktop) | SPA / PWA | Venue managers, floor staff, operators | +| Web (Mobile) | Responsive PWA | Players, dealers | +| Native Mobile (future) | iOS / Android | Players, dealers | +| Chromecast Receiver | Custom receiver app | Display screens at venues | +| 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, credit lines, and financial data demand strong security. But the UX should never feel like a bank app — it should feel like a poker app. +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.*