pokertrip/docs/2026-03-18-pokertrip-design.md

PokerTrip — Personal Poker Tracker Design Spec

Overview

A personal poker tracker PWA for a tournament player based in Copenhagen. Tracks ad-hoc home sessions across local venues and structured poker trips abroad, each with isolated budgets. Mobile-first "cockpit" for fast input at the table, desktop "command center" for analysis and trip planning. Includes an AI-powered trip research agent that builds tournament schedules from web searches, URLs, and uploaded images (venue flyers, Facebook posts, etc.).

Designed as a personal tool with architectural choices that support a future SaaS launch (multi-user, shared tournament knowledge base, tiered AI access).

User Context

• Danish developer in Copenhagen, plays tournaments ad-hoc (2 jobs + family = no fixed schedule)
• Travels for poker a few times a year (upcoming Manila trip May 2026) — trips are where structured planning and budget tracking matter
• Runs Proxmox on Hetzner with Nginx Proxy Manager, PBS with off-site backup
• Prefers Catppuccin Mocha theming, JetBrains Mono font
• Does not code — Claude builds everything

Core Concepts

Home vs. Trip

Everything is either Home or a Trip.

• Home: Your default poker life. Ad-hoc sessions at local venues in Denmark. No fixed schedule. One ongoing budget/P&L. Rich filtering by venue(s), buyin range, date range, game type.
• Trip: A planned poker trip with its own dates, location, budget, and tournament schedule. Budget is soft — you set an intended amount but can exceed it. Trips have a lifecycle: planning → active → completed.

Three Layers of Tournament Data

1. Global Events (public, system-level)

   • Scraped/curated nightly from Hendon Mob, WPT, WSOP, PokerStars Live, APT, etc.
   • Series-level data: "EPT Barcelona, July 15-28"
   • Background River job, builds a baseline calendar of the poker world
   • Available to all users as a browsable calendar

2. Location Knowledge (community-contributed, anonymized)

   • When a user runs AI research for a location/date range and approves results, the venue and schedule data enriches a shared pool
   • No attribution — can't see who contributed, just that data exists
   • Another user researching the same location gets this as context fed into their own research run (not free access — you must run your own research to benefit)

3. My Trips (private, per-user)

   • Your trip: name, dates, budget, which events you're registered for, your results
   • Completely invisible to others unless explicitly shared via a friends feature (SaaS)

Venue Profiles (the "app learns" feature)

Users set up venue profiles: "Casino Copenhagen → Thursday → NLH, 500 DKK, 50K GTD, 10K starting stack". When logging a session at that venue on that day, the app pre-fills these defaults. User can always override. Pattern-based auto-detection from history is a future enhancement — manual profiles first.

Tournament Snapshots

During an active session, you can take a photo of the tournament screen (the TV showing clock/blinds/players). A cheap vision model (e.g. Gemini Flash, Haiku) extracts: level, blinds, ante, players remaining, average stack, total chips, next break, prize pool. You manually enter your own stack size. This creates a timestamped snapshot enabling:

• Stack trajectory charts per session (your stack in BB over time)
• Your stack vs. average stack overlay
• "At what BB count do I tend to bust?" analysis
• Smarter re-entry tilt guard (uses live data from last snapshot)

Re-entry Tilt Guard

When tapping "Re-entry", the app calculates and displays: how many BBs you'll get, total invested so far, break-even cash amount needed. Forces a moment of rational thought before emotional re-entry decisions. Uses blind structure from venue profiles or trip schedule data, enhanced by snapshot data if available.

Data Model

Users

Column	Type	Notes
id	UUID	PK
email	TEXT	unique
password_hash	TEXT	bcrypt
display_name	TEXT
settings	JSONB	preferred currency, AI config, snapshot model, etc.
created_at	TIMESTAMPTZ
updated_at	TIMESTAMPTZ

Venues

Column	Type	Notes
id	UUID	PK
name	TEXT
short_name	TEXT
city	TEXT
country	TEXT
area	TEXT	neighborhood/district
type	TEXT	tournament / cash / both
notes	TEXT
color	TEXT	hex color for UI
visibility	TEXT	public / private
created_by_user_id	UUID	FK → users
created_at	TIMESTAMPTZ

Venue Profiles (per-user defaults)

Column	Type	Notes
id	UUID	PK
user_id	UUID	FK → users
venue_id	UUID	FK → venues
day_of_week	INT	0=Sunday, 1=Monday, etc. (nullable for "any day" default)
default_game_type	TEXT	NLH, PLO, etc.
default_buyin	INT	in minor currency unit
default_currency	TEXT	DKK, PHP, USD, EUR, etc.
default_gtd	INT	nullable
starting_stack	INT	chips
blind_structure	JSONB	array of {level, small, big, ante, duration_min}
notes	TEXT

Trips

Column	Type	Notes
id	UUID	PK
user_id	UUID	FK → users
name	TEXT	"Manila May 2026"
location	TEXT	"Manila"
country	TEXT	"Philippines"
start_date	DATE
end_date	DATE
planned_budget	INT	soft ceiling
currency	TEXT
status	TEXT	planning / active / completed
created_at	TIMESTAMPTZ
updated_at	TIMESTAMPTZ

Global Events (scraped)

Column	Type	Notes
id	UUID	PK
name	TEXT	"EPT Barcelona"
series	TEXT	EPT, WPT, WSOP, etc.
location	TEXT
country	TEXT
start_date	DATE
end_date	DATE
source_url	TEXT	where it was scraped from
details	JSONB	flexible extra data
scraped_at	TIMESTAMPTZ

Location Schedules (community-contributed, anonymized)

Column	Type	Notes
id	UUID	PK
location_key	TEXT	e.g. "manila-2026-05" for dedup/lookup
venue_id	UUID	FK → venues
date	DATE
time	TIME
event_code	TEXT	"#29A" etc.
name	TEXT
buyin	INT
currency	TEXT
guarantee	INT	nullable
format	TEXT	NLH, PLO, NLH PKO, etc.
notes	TEXT
multi_day	BOOLEAN
multi_day_info	TEXT	"Day 2: May 9, Final: May 10"
starting_stack	INT	nullable
blind_structure	JSONB	nullable
source	TEXT	"ai_research" / "manual" / "scraped"
created_at	TIMESTAMPTZ

Sessions (the core table — every tournament/cash game played)

Column	Type	Notes
id	UUID	PK
user_id	UUID	FK → users
venue_id	UUID	FK → venues
trip_id	UUID	FK → trips, nullable (null = Home)
schedule_entry_id	UUID	FK → location_schedules, nullable
date	DATE
start_time	TIMESTAMPTZ
end_time	TIMESTAMPTZ	nullable (set when session ends)
game_type	TEXT	NLH, PLO, etc.
session_type	TEXT	tournament / cash
buyin	INT
currency	TEXT
payout	INT	nullable
finish_position	INT	nullable
field_size	INT	nullable
status	TEXT	registered / playing / busted / cashed / day2 / skipped
late_reg	BOOLEAN	default false
entry_level	INT	nullable — what level you joined at
entry_blinds	TEXT	nullable — e.g. "100/200"
notes	TEXT
created_at	TIMESTAMPTZ
updated_at	TIMESTAMPTZ

Session Re-entries

Column	Type	Notes
id	UUID	PK
session_id	UUID	FK → sessions
timestamp	TIMESTAMPTZ	when the re-entry happened
level	INT	nullable
blinds	TEXT	nullable — e.g. "200/400"
stack_received	INT	nullable — chips received
cost	INT	re-entry cost (may differ from original buyin)

Session Snapshots

Column	Type	Notes
id	UUID	PK
session_id	UUID	FK → sessions
timestamp	TIMESTAMPTZ
my_stack	INT	user-entered
level	INT	extracted from image
blinds_small	INT	extracted
blinds_big	INT	extracted
ante	INT	nullable, extracted
players_remaining	INT	nullable, extracted
average_stack	INT	nullable, extracted
total_chips	BIGINT	nullable, extracted
next_break	TEXT	nullable, extracted
prize_pool	INT	nullable, extracted
bb_count	NUMERIC	calculated: my_stack / blinds_big
image_url	TEXT	path to stored image

Research Jobs

Column	Type	Notes
id	UUID	PK
user_id	UUID	FK → users
trip_id	UUID	FK → trips
status	TEXT	pending / running / completed / failed
prompt	TEXT	user's research request
model	TEXT	model ID used
provider_endpoint	TEXT	OpenRouter/Requesty URL
attachments	JSONB	array of {type: "image"/"url", value: "..."}
results	JSONB	structured venue + schedule data proposed by AI
conversation	JSONB	full tool-use conversation for refinement context
created_at	TIMESTAMPTZ
updated_at	TIMESTAMPTZ

Uploads

Column	Type	Notes
id	UUID	PK
user_id	UUID	FK → users
path	TEXT	filesystem path
content_type	TEXT	image/jpeg, image/png, etc.
size_bytes	BIGINT
purpose	TEXT	research / snapshot
created_at	TIMESTAMPTZ

Architecture

Phone/Desktop (React PWA)
  ├── Optimistic local state (in-memory + localStorage cache)
  ├── Background sync → API
  └── SSE connection for real-time updates (research progress, etc.)
        │
        ▼
Go API (single binary, embeds React frontend)
  ├── Chi router
  ├── Auth middleware (JWT + refresh tokens)
  ├── REST endpoints (/api/v1/*)
  ├── SSE endpoint for live updates
  ├── River job queue (in-process, Postgres-backed)
  │     ├── Sync/write jobs
  │     ├── AI research jobs (search → fetch → structure)
  │     ├── Snapshot OCR jobs
  │     └── Nightly global events scraper
  └── SearXNG client (for AI web search tool-use)
        │
        ▼
Postgres (10.5.0.109)
  ├── Application data
  └── River job queue tables

SearXNG (LXC on Proxmox)
  └── Metasearch engine, self-hosted, no API keys

Write Path (message queue pattern)

Every mutation from the client follows fire-and-forget:

1. Client makes optimistic UI update (instant)
2. POST/PATCH to API → returns 202 Accepted immediately
3. River job processes the actual DB write
4. If failure, client resyncs on next pull
5. SSE pushes confirmations for critical operations

The UI is always ahead of the database. No lag, ever.

API Design

All endpoints versioned under /api/v1/. All write endpoints return 202 Accepted. All list endpoints support cursor pagination + query param filters.

/api/v1/auth
  POST   /register
  POST   /login             → JWT access token + refresh token (httpOnly cookie)
  POST   /refresh           → rotate tokens

/api/v1/me
  GET    /                  → user profile + settings
  PATCH  /                  → update settings

/api/v1/venues
  GET    /                  → list (public + user's private)
  POST   /
  PATCH  /:id

/api/v1/venue-profiles
  GET    /                  → user's venue defaults
  PUT    /:venue_id/:dow    → set/update default

/api/v1/sessions
  GET    /                  → filterable: venue, trip, date range, buyin range, game type, status
  POST   /
  PATCH  /:id              → status changes, payout, notes, end time
  POST   /:id/reentry      → add re-entry (triggers tilt guard response)
  POST   /:id/snapshot      → upload tournament screen photo + stack size

/api/v1/trips
  GET    /
  POST   /
  PATCH  /:id
  GET    /:id/schedule      → trip's tournament schedule

/api/v1/schedule
  GET    /                  → location schedules (query by location_key, date range)
  POST   /                  → manually add schedule entry

/api/v1/research
  POST   /                  → start AI research job
  GET    /:id               → job status + results
  POST   /:id/refine        → iterate with additional context/images
  POST   /:id/approve       → accept results → writes to venues + location_schedules

/api/v1/global-events
  GET    /                  → browse scraped series (filterable by date, location)

/api/v1/events
  GET    /stream            → SSE (research progress, sync confirmations)

/api/v1/settings/models
  GET    /                  → quick picks + full model list from provider API

AI Research System

Research Flow

1. User creates a trip, hits "Research"
2. Chat-like interface: text prompt + image uploads + URL links + model picker
3. POST /research → River job queued
4. Go backend calls chosen model via OpenRouter/Requesty (OpenAI-compatible endpoint)
5. Model receives system prompt + tools:
   • search(query) → hits self-hosted SearXNG
   • fetch_url(url) → fetches and extracts page content
   • analyze_image(image) → model's own vision capability on uploaded images
   • create_venue(data) → proposes a new venue
   • create_schedule_entry(data) → proposes a tournament entry
6. SSE streams progress to browser ("Searching... Found venue... Extracting schedule...")
7. Results presented as proposed schedule cards with Accept/Edit/Remove per entry
8. User can refine ("also check 9D Poker Club") → POST /research/:id/refine
9. User approves → venues (public) + schedule entries written to DB

Shared Knowledge Context

Before starting research, system checks for existing location knowledge for the target location + date range. If found, it's provided as context to the AI ("We already know about these venues and events — build on this"). This requires the user to run their own research — no free access to the knowledge base without contributing.

Snapshot OCR Flow

1. During active session, tap camera button
2. Snap tournament screen → upload image
3. POST /sessions/:id/snapshot with image + user's stack size
4. River job sends image to snapshot model (cheap/fast vision model, configured separately in settings)
5. Model extracts: level, blinds, ante, players, average stack, etc.
6. Returns pre-filled fields → user confirms/corrects → saved

Model Management (Settings UI)

AI Settings:
  Provider:        [OpenRouter ▾]  (OpenRouter / Requesty / Custom)
  Endpoint URL:    [https://openrouter.ai/api/v1]
  API Key:         [••••••••••••]

  Research Model:  Quick picks: Sonnet, Opus, GPT-4o, Gemini Pro, Grok
                   [🔍 Search all models...]

  Snapshot Model:  Quick picks: Haiku, Gemini Flash, GPT-4o-mini
                   [🔍 Search all models...]

  🖼️ Vision support indicator per model

Quick picks populated from provider's /models endpoint, filtered to top models from Anthropic, OpenAI, Google, xAI. Fuzzy search for the full list.

Frontend

Shared Principles

• Catppuccin Mocha color palette throughout
• JetBrains Mono / Fira Code font
• Dark mode only
• PWA: manifest.json + service worker (Workbox) for offline caching
• Optimistic UI: every action feels instant

Mobile Cockpit (< 768px)

The in-the-moment tool. Speed and touch-friendliness above all.

Top toggle: Home | Trip (Trip only visible when an active trip exists)

Home mode:

• "Log a session" prominent button
• Today's venue suggestion (from venue profiles for this day of week)
• Last 3-5 sessions as quick history
• Tap "Log" → pick venue (favorites first, search others) → pre-filled from venue profile → confirm → live session
• Active session: timer, big thumb-friendly action buttons (Rebuy, Add-on, Bust, Cash, Made Day 2, Snapshot)
• Re-entry tilt guard modal before confirming re-entry
• "Cash" → input payout + finish position → end session

Trip mode:

• Today's schedule (card-style, like Manila JSX)
• Filter by venue
• Status badges and action buttons per tournament
• Budget bar: spent vs. planned, current P&L
• Swipe between days

Session entry captures:

• Venue, date, game type, buyin, currency
• Start time (auto), end time (when you tap "done")
• Late registration flag + entry level/blinds (optional)
• Re-entries (tracked individually with timestamp, level, blinds, cost)
• Payout, finish position, field size (on completion)
• Notes
• Snapshots (photos of tournament screen + your stack)

Desktop Dashboard (≥ 768px)

The analysis and planning tool.

Sidebar navigation: Home, Trips, Stats, Venues, Settings

Home view:

• Session history table with powerful filtering: date range, venue(s), buyin range, game type, result
• Summary stats bar: total sessions, P&L, ROI, avg buyin, avg cash, ITM%
• Filters update everything live

Trip view:

• Trip list → drill into trip → full schedule explorer
• Side panel: budget tracker (planned vs. actual), session results, daily breakdown
• Research tab: start/refine AI research, review proposed schedules, approve

Stats view:

• P&L over time (line chart)
• By venue (bar chart)
• By game type, by buyin range
• Home vs. Trips breakdown
• Monthly/quarterly/yearly views
• Late reg vs. on-time performance comparison
• Stack trajectory charts (from snapshots)
• Re-entry analysis (ROI with vs. without re-entries)
• All filterable with same filter system

Venues view:

• Manage venues (public/private)
• Set up venue profiles (day-of-week defaults, blind structures, starting stacks)

Settings view:

• Profile (email, display name, preferred currency)
• AI configuration (provider, API key, research model, snapshot model)
• Model picker with quick picks + fuzzy search

Auth & Multi-tenancy

Current (personal tool)

• Email + password registration (bcrypt)
• JWT access token (15 min) + refresh token (30 days, httpOnly cookie)
• All queries scoped by user_id
• No email verification (single user)

Data Visibility Rules

Data	Visibility
Global events	Everyone
Location schedules	Users who have run research (give-to-get)
Public venues	Everyone
Private venues	Creator only (redacted as "Private Venue" in any shared context)
Trips	Owner only
Sessions & results	Owner only
Budgets	Owner only
Snapshots	Owner only
Venue profiles	Owner only
Research jobs	Owner only (approved venues/schedules become shared)

Tech Stack

Backend

• Go (latest stable)
• chi — lightweight router
• pgx — Postgres driver
• sqlc — type-safe SQL → Go codegen
• goose — migrations
• river — Postgres-backed job queue (no Redis)
• golang-jwt/jwt/v5 — JWT
• golang.org/x/crypto/bcrypt — password hashing
• embed — React frontend baked into binary

Frontend

• React + TypeScript (Vite)
• Tailwind CSS (Catppuccin Mocha palette)
• Framer Motion (animations)
• Recharts (stats/charts)
• Workbox (PWA/service worker)
• Zustand or Jotai (lightweight state)

Infrastructure

• Postgres (10.5.0.109, database: pokertrip)
• SearXNG (self-hosted LXC on Proxmox)
• Nginx Proxy Manager (existing, SSL termination)

Deployment

Single Go binary embeds the built React frontend. One process, one port.

poker.georgsen.dk
  → Nginx Proxy Manager (SSL)
    → Go binary :8080
      ├── /           → embedded React SPA
      ├── /api/v1/*   → API
      └── /api/v1/events/stream → SSE

Environment config via .env file (gitignored). See .env.example for template.

Dev experience:

• make dev — Go hot reload (Air) + Vite dev server with proxy
• make build — builds React, embeds into Go binary
• make migrate — runs Postgres migrations (goose)

Project Structure

pokertrip/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── api/
│   │   ├── auth.go
│   │   ├── sessions.go
│   │   ├── trips.go
│   │   ├── venues.go
│   │   ├── research.go
│   │   ├── snapshots.go
│   │   └── middleware.go
│   ├── db/
│   │   ├── migrations/
│   │   ├── queries/
│   │   └── sqlc.yaml
│   ├── jobs/
│   │   ├── research.go
│   │   ├── scraper.go
│   │   └── snapshot_ocr.go
│   ├── ai/
│   │   ├── client.go
│   │   ├── tools.go
│   │   └── models.go
│   ├── storage/
│   │   └── local.go
│   └── config/
│       └── config.go
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── mobile/
│   │   │   ├── desktop/
│   │   │   └── shared/
│   │   ├── hooks/
│   │   ├── stores/
│   │   ├── api/
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── public/
│   │   ├── manifest.json
│   │   └── sw.js
│   ├── index.html
│   ├── vite.config.ts
│   ├── tailwind.config.ts
│   └── package.json
├── docs/
│   ├── manila-poker-tracker.jsx   ← reference JSX for Manila trip UI
│   ├── saas-considerations.md
│   └── 2026-03-18-pokertrip-design.md  ← this file
├── .env
├── .env.example
├── .gitignore
├── Makefile
├── Dockerfile
└── go.mod