# PokerTrip — GSD Kickoff Prompt

## Project

Build **PokerTrip**, a personal poker tournament tracker as a PWA. Go backend + React frontend + PostgreSQL.

## Key Documents

Read these before planning:

1. **Design spec**: `docs/2026-03-18-pokertrip-design.md` — the full architecture, data model, API design, frontend layout, AI research system, and tech stack. This is the source of truth.
2. **Manila JSX reference**: `docs/manila-poker-tracker.jsx` — a working React component for a Manila poker trip tracker. Use as UI/UX reference for the trip mode experience (card layout, action buttons, status flow, budget display, Catppuccin Mocha theming). The data is hardcoded here — in the real app it comes from the database.
3. **SaaS considerations**: `docs/saas-considerations.md` — a checklist of things to add when going multi-tenant. Don't build these now, but make architectural choices that don't block them later (user-scoped data, storage interface abstraction, etc.).

## Tech Stack

- **Backend**: Go, Chi (router), pgx (Postgres driver), sqlc (codegen), goose (migrations), River (Postgres-backed job queue), golang-jwt, bcrypt
- **Frontend**: React + TypeScript, Vite, Tailwind CSS (Catppuccin Mocha palette), Framer Motion, Recharts, Workbox (PWA), Zustand (state)
- **Database**: PostgreSQL at `10.5.0.109:5432/pokertrip` (credentials in `.env`)
- **AI**: OpenAI-compatible endpoint (OpenRouter/Requesty), self-hosted SearXNG for web search
- **Deploy**: Single Go binary with embedded React frontend via `embed.FS`

## What To Build

The design spec covers everything in detail, but the major systems are:

1. **Database schema + migrations** — all tables from the data model section
2. **Auth** — email/password, JWT access + refresh tokens, user-scoped queries
3. **Venues** — CRUD, public/private visibility, venue profiles (per-user day-of-week defaults)
4. **Sessions** — the core: create, status transitions, re-entries (with tilt guard data), end session, filtering
5. **Trips** — CRUD, budget tracking, link to location schedules
6. **Tournament snapshots** — image upload, vision model OCR extraction, stack tracking
7. **AI research system** — River job, OpenAI-compatible client with tool-use (SearXNG search, URL fetch, image analysis), SSE progress streaming, review/refine/approve flow
8. **Global events scraper** — nightly River job, Hendon Mob etc.
9. **Frontend mobile cockpit** — Home/Trip toggle, fast session entry, action buttons, tilt guard modal, snapshot camera
10. **Frontend desktop dashboard** — session history with filters, trip explorer, stats/charts, venue management, settings (AI config, model picker)
11. **PWA** — manifest, service worker, offline support, optimistic sync

## Architecture Principles

- Most writes are fire-and-forget from the client (202 Accepted, River processes async) — exceptions: auth (synchronous, returns tokens) and research approval (synchronous, returns 200 after write)
- UI is always optimistic — never wait for DB confirmation
- All data is user-scoped (ready for multi-tenant)
- Storage interface abstraction (local filesystem now, S3-compatible later)
- Separate model settings for research (powerful) vs. snapshot OCR (cheap/fast)
- Shared tournament knowledge is anonymized and give-to-get (must run own research to access community data)

## User Context

The user (Mikkel) does not code — Claude builds everything. He plays poker tournaments ad-hoc in Denmark and plans trips abroad a few times a year. Mobile UX is critical — he'll use this at the poker table. Desktop is for analysis and trip planning at home.