diff --git a/README.md b/README.md index 5d6338d..c3d3918 100644 --- a/README.md +++ b/README.md @@ -22,25 +22,43 @@ PVM is a comprehensive management system for poker venues of any size. It handle - **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 +- **Player Accounts** — One account across all venues, memberships, and game history. Players sign up for PVM first, then join venues. - **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 +- **Venue Display System** — Push live clocks, seatings, waitlists, and info to any TV via Android display clients with mDNS auto-discovery +- **Local Node Support** — Optional on-premise Raspberry Pi 5 proxy (Docker-based) for zero-downtime operation during internet outages (up to 72h offline) ## Architecture ``` - PVM Cloud (SaaS) ◄── near-realtime sync ──► Venue Local Nodes (RPi5) +Hetzner PVE (LXC + Docker) +├── Rust API (Axum) + WebSocket Gateway +├── PostgreSQL 16 + DragonflyDB +├── NATS + JetStream +└── SvelteKit Web Apps │ - ├── Web App (managers, staff, players, dealers) - ├── Mobile PWA / Native App (players, dealers) - └── Chromecast Receiver (venue display screens) + ├── near-realtime event sync (NATS) ──► Venue RPi5 Nodes (Docker) + ├── Web App / PWA (managers, staff, players, dealers) + └── Venue TVs (Android display client, cloud fallback) ``` +## Tech Stack + +| Layer | Technology | +|-------|-----------| +| Backend | Rust + Axum | +| Frontend | SvelteKit (Svelte 5) + shadcn-svelte + Tailwind v4 | +| Cloud DB | PostgreSQL 16+ | +| Local DB | libSQL (embedded) | +| Cache | DragonflyDB | +| Messaging | NATS + JetStream | +| Auth | Custom JWT + RBAC | +| API | REST + OpenAPI 3.1 | +| Infra | Hetzner PVE, Docker, Forgejo Actions | + ## 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 +- **[Tech Stack Research](docs/TECH_STACK_RESEARCH.md)** — Comprehensive technology decisions and reasoning --- diff --git a/docs/VISION.md b/docs/VISION.md index bf883e0..37f49f4 100644 --- a/docs/VISION.md +++ b/docs/VISION.md @@ -59,11 +59,11 @@ PVM is a comprehensive SaaS platform for managing poker venues, tournaments, cas ### 3. Player Accounts -- **Universal PVM Account**: One account, all venues. Player profile, game history, and preferences travel with the player. +- **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, limits, and settlement workflows. +- **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 @@ -72,16 +72,16 @@ PVM is a comprehensive SaaS platform for managing poker venues, tournaments, cas - **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 +### 5. Venue Display System -- **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**: +- **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 slides + - Custom announcements & information slideshows - Leaderboards and results ### 6. Venue Operations @@ -98,10 +98,12 @@ PVM is a comprehensive SaaS platform for managing poker venues, tournaments, cas 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. +- **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. --- @@ -109,10 +111,9 @@ For venues that subscribe to the local node option: | 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 | +| 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 | --- @@ -121,7 +122,7 @@ For venues that subscribe to the local node option: 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. +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.