mikkel/pokertrip
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
pokertrip/docs/gsd-kickoff.md
Mikkel Georgsen 38c7877765 Fix spec review findings: data model gaps, API completeness, missing sections 
- Add contributed_by_user_id + research_job_id to location_schedules (give-to-get audit trail)
- Add reentry type field (reentry/rebuy/addon distinction)
- Consistent minor currency unit annotations on all monetary columns
- Add exchange_rate_to_home to sessions for cross-currency stats
- Add timestamps to venue_profiles and location_schedules
- Add missing API endpoints: GET session detail, DELETE endpoints, GET snapshots/reentries
- Document 202 Accepted exceptions (auth, research approval are synchronous)
- Add multipart/form-data upload flow documentation
- Add tilt guard response contract
- Add session status state machine diagram
- Add currency conversion strategy
- Add offline sync strategy (localStorage queue, last-write-wins)
- Add API error response format and cursor pagination format
- Add rate limiting on auth endpoints
- Resolve Zustand vs Jotai → Zustand
- Align Go version across docs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-18 09:40:46 +00:00

3.6 KiB
Raw Blame History

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.