mikkel/pvm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update README and VISION with finalized tech stack decisions

Browse source 
Align both documents with resolved tech stack choices:
- Hetzner PVE hosting, Docker-based RPi5 nodes
- Android display client with mDNS (no Chromecast dependency)
- Event-based NATS sync, 72h offline limit
- PVM signup-first accounts, no money handling
- Add tech stack summary table to README

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Mikkel Georgsen 2026-02-08 03:12:56 +01:00
parent 2bb381a0a3
commit 995a8123e6
2 changed files with 43 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
README.md
View file

@ -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 - **Tournament Management** — Planning, live clocks, seating, registration, results, and recurring series
- **Cash Game Operations** — Table tracking, waiting lists, game types, and session history - **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 - **Dealer Coordination** — Scheduling, availability, shift swaps, and cross-venue mobility
- **Display Streaming** — Push live clocks, seatings, and info to Chromecast screens throughout the venue - **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 for zero-downtime operation during internet outages - **Local Node Support** — Optional on-premise Raspberry Pi 5 proxy (Docker-based) for zero-downtime operation during internet outages (up to 72h offline)
## Architecture ## 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) ├── near-realtime event sync (NATS) ──► Venue RPi5 Nodes (Docker)
├── Mobile PWA / Native App (players, dealers) ├── Web App / PWA (managers, staff, players, dealers)
└── Chromecast Receiver (venue display screens) └── 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 ## Documentation
- **[Vision & Feature Overview](docs/VISION.md)** — The full product vision and feature roadmap - **[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
--- ---

33
docs/VISION.md
View file

@ -59,11 +59,11 @@ PVM is a comprehensive SaaS platform for managing poker venues, tournaments, cas
### 3. Player Accounts ### 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. - **Venue Discovery**: Browse public venues, view upcoming events, and join with a tap.
- **Private Venues**: Invite-only access with approval workflows. - **Private Venues**: Invite-only access with approval workflows.
- **Membership Management**: Venue-specific membership tiers with benefits, dues tracking, and renewal automation. - **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 ### 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.). - **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. - **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. - **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 Chromecast destinations and select what each screen displays. - **Screen Manager**: A dashboard to assign display destinations and select what each screen shows. Group screens by area (tournament room, cash room, lobby).
- **Stream Types**: - **Display Content**:
- Tournament live clock - Tournament live clock
- Current seating charts - Current seating charts
- Waiting lists - Waiting lists
- Cash game availability - Cash game availability
- Custom announcements & information slides - Custom announcements & information slideshows
- Leaderboards and results - Leaderboards and results
### 6. Venue Operations ### 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: For venues that subscribe to the local node option:
- **Hardware**: Raspberry Pi 5 (or equivalent small-form-factor device). - **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. - **Runtime**: Docker on stock Raspberry Pi OS. Two containers: PVM node (Rust binary with embedded libSQL) + NATS leaf node.
- **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). - **Role**: Acts as a local proxy and offline cache. All venue operations can continue uninterrupted during internet outages for up to 72 hours.
- **Security**: The local node authenticates with the cloud via mutual TLS. Local data is encrypted at rest. - **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.
- **Management**: Nodes are remotely provisioned and updated from the PVM cloud admin. - **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 | | Platform | Type | Primary Users |
|----------|------|---------------| |----------|------|---------------|
| Web (Desktop) | SPA / PWA | Venue managers, floor staff, operators | | Web (Desktop) | SvelteKit SPA / PWA | Venue managers, floor staff, operators |
| Web (Mobile) | Responsive PWA | Players, dealers | | Web (Mobile) | Responsive PWA (Capacitor later) | Players, dealers |
| Native Mobile (future) | iOS / Android | Players, dealers | | Venue Displays | Android display client app | TVs throughout the venue |
| Chromecast Receiver | Custom receiver app | Display screens at venues |
| Local Node UI | Lightweight admin panel | On-site tech / venue manager | | 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. 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. 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. 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. 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.