golfgame/docs/v2/V2_00_MASTER_PLAN.md

Golf Card Game - V2 Master Plan

Overview

Transform the current single-server Golf game into a production-ready, hostable platform with:

• Event-sourced architecture for full game replay and audit trails
• User accounts with authentication, password reset, and profile management
• Admin tools for moderation and system management
• Leaderboards with player statistics
• Scalable hosting options (self-hosted or cloud)
• Export/playback for sharing memorable games

---

Document Structure (VDD)

This plan is split into independent vertical slices. Each document is self-contained and can be worked on by a separate agent.

Document	Scope	Dependencies
V2_01_EVENT_SOURCING.md	Event classes, store, state rebuilding	None (foundation)
V2_02_PERSISTENCE.md	Redis cache, PostgreSQL, game recovery	01
V2_03_USER_ACCOUNTS.md	Registration, login, password reset, email	02
V2_04_ADMIN_TOOLS.md	Admin dashboard, moderation, system stats	03
V2_05_STATS_LEADERBOARDS.md	Stats aggregation, leaderboard API/UI	03
V2_06_REPLAY_EXPORT.md	Game replay, export, share links	01, 02
V2_07_PRODUCTION.md	Docker, deployment, monitoring, security	All

---

Current State (V1)

Client (Vanilla JS) <──WebSocket──> FastAPI Server <──> SQLite
                                          │
                                    In-memory rooms
                                    (lost on restart)

What works well:

• Game logic is solid and well-tested
• CPU AI with 8 distinct personalities
• Flexible house rules system (15+ options)
• Real-time multiplayer via WebSockets
• Basic auth system with invite codes

Limitations:

• Single server, no horizontal scaling
• Game state lost on server restart
• Move logging exists but duplicates state
• No persistent player stats or leaderboards
• Limited admin capabilities
• No password reset flow
• No email integration

---

V2 Target Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                            Clients                                   │
│                   (Browser / Future: Mobile)                         │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ WebSocket + REST API
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      FastAPI Application                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ Command  │ │  Event   │ │  State   │ │  Query   │ │   Auth   │  │
│  │ Handler  │─► Store    │─► Builder  │ │ Service  │ │ Service  │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                            │
│  │  Admin   │ │  Stats   │ │  Email   │                            │
│  │ Service  │ │ Worker   │ │ Service  │                            │
│  └──────────┘ └──────────┘ └──────────┘                            │
└───────┬───────────────┬───────────────┬───────────────┬────────────┘
        │               │               │               │
        ▼               ▼               ▼               ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│    Redis     │ │  PostgreSQL  │ │  PostgreSQL  │ │    Email     │
│ (Live State) │ │   (Events)   │ │ (Users/Stats)│ │   Provider   │
│  (Pub/Sub)   │ │              │ │              │ │  (Resend)    │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘

---

Tech Stack

Layer	Technology	Reasoning
Web framework	FastAPI (keep)	Already using, async, fast
WebSockets	Starlette (keep)	Built into FastAPI
Live state cache	Redis	Fast, pub/sub, TTL, battle-tested
Event store	PostgreSQL	JSONB, robust, great tooling
User database	PostgreSQL	Same instance, keep it simple
Background jobs	arq	Async, Redis-backed, lightweight
Email	Resend	Simple API, good free tier, reliable
Containerization	Docker	Consistent deployment
Orchestration	Docker Compose	Start simple, K8s if needed

New Dependencies

# requirements.txt additions
redis>=5.0.0
asyncpg>=0.29.0           # Async PostgreSQL
sqlalchemy>=2.0.0         # ORM for complex queries
alembic>=1.13.0           # Database migrations
arq>=0.26.0               # Background task queue
pydantic-settings>=2.0    # Config management
resend>=0.8.0             # Email service
python-jose[cryptography] # JWT tokens
passlib[bcrypt]           # Password hashing

---

Phases & Milestones

Phase 1: Event Infrastructure (Foundation)

Goal: Emit events alongside current code, validate replay works

Milestone	Description	Document
Event classes defined	All gameplay events as dataclasses	01
Event store working	PostgreSQL persistence	01
Dual-write enabled	Events emitted without breaking current code	01
Replay validation	Test proves events recreate identical state	01
Rate limiting on auth	Brute force protection	07

Phase 2: Persistence & Recovery

Goal: Games survive server restarts

Milestone	Description	Document
Redis state cache	Live game state in Redis	02
Pub/sub ready	Multi-server WebSocket fan-out	02
Game recovery	Rebuild games from events on startup	02
Graceful shutdown	Save state before stopping	02

Phase 3a: User Accounts

Goal: Full user lifecycle management

Milestone	Description	Document
Email service integrated	Resend configured and tested	03
Registration with verification	Email confirmation flow	03
Password reset flow	Forgot password via email token	03
Session management	View/revoke sessions	03
Account settings	Profile, preferences, deletion	03

Phase 3b: Admin Tools

Goal: Moderation and system management

Milestone	Description	Document
Admin dashboard	User list, search, metrics	04
User management	Ban, unban, force password reset	04
Game moderation	View any game, end stuck games	04
System monitoring	Active games, users online, events/hour	04
Audit logging	Track admin actions	04

Phase 4: Stats & Leaderboards

Goal: Persistent player statistics

Milestone	Description	Document
Stats schema	PostgreSQL tables for aggregated stats	05
Stats worker	Background job processing events	05
Leaderboard API	REST endpoints	05
Leaderboard UI	Client display	05
Achievement system	Badges and milestones (stretch)	05

Phase 5: Replay & Export

Goal: Share and replay games

Milestone	Description	Document
Export API	Download game as JSON	06
Import/load	Upload and replay	06
Replay UI	Playback controls, scrubbing	06
Share links	Public /replay/{id} URLs	06

Phase 6: Production

Goal: Deployable, monitored, secure

Milestone	Description	Document
Dockerized	All services containerized	07
Health checks	/health endpoint with dependency checks	07
Metrics	Prometheus metrics	07
Error tracking	Sentry integration	07
Deployment guide	Step-by-step for VPS/cloud	07

---

File Structure (Target)

golfgame/
├── client/                     # Frontend (enhance incrementally)
│   ├── index.html
│   ├── app.js
│   ├── components/             # New: modular UI components
│   │   ├── leaderboard.js
│   │   ├── replay-controls.js
│   │   └── admin-dashboard.js
│   └── ...
├── server/
│   ├── main.py                 # FastAPI app entry point
│   ├── config.py               # Settings from env vars
│   ├── dependencies.py         # FastAPI dependency injection
│   ├── models/
│   │   ├── events.py           # Event dataclasses
│   │   ├── user.py             # User model
│   │   └── game_state.py       # State rebuilt from events
│   ├── stores/
│   │   ├── event_store.py      # PostgreSQL event persistence
│   │   ├── state_cache.py      # Redis live state
│   │   └── user_store.py       # User persistence
│   ├── services/
│   │   ├── game_service.py     # Command handling, event emission
│   │   ├── auth_service.py     # Authentication, sessions
│   │   ├── email_service.py    # Email sending
│   │   ├── admin_service.py    # Admin operations
│   │   ├── stats_service.py    # Leaderboard queries
│   │   └── replay_service.py   # Export, import, playback
│   ├── routers/
│   │   ├── auth.py             # Auth endpoints
│   │   ├── admin.py            # Admin endpoints
│   │   ├── games.py            # Game/replay endpoints
│   │   └── stats.py            # Leaderboard endpoints
│   ├── workers/
│   │   └── stats_worker.py     # Background stats aggregation
│   ├── middleware/
│   │   ├── rate_limit.py       # Rate limiting
│   │   └── auth.py             # Auth middleware
│   ├── ai/                     # Keep existing AI code
│   │   └── ...
│   └── tests/
│       ├── test_events.py
│       ├── test_replay.py
│       ├── test_auth.py
│       └── ...
├── migrations/                  # Alembic migrations
│   ├── versions/
│   └── env.py
├── docker/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── docker-compose.prod.yml
├── docs/
│   └── v2/                     # These planning documents
│       ├── V2_00_MASTER_PLAN.md
│       ├── V2_01_EVENT_SOURCING.md
│       └── ...
└── scripts/
    ├── migrate.py              # Run migrations
    ├── create_admin.py         # Bootstrap admin user
    └── export_game.py          # CLI game export

---

Decision Log

Decision	Choice	Rationale
Event store DB	PostgreSQL	JSONB support, same DB as users, simpler ops
Email provider	Resend	Simple API, good free tier (3k/mo), reliable
Background jobs	arq	Async-native, Redis-backed, lightweight
Session storage	Redis	Fast, TTL support, already using for state
Password hashing	bcrypt	Industry standard, built-in work factor
JWT vs sessions	Both	JWT for API, sessions for WebSocket

---

Open Questions

1. Guest play vs required accounts?

   • Decision: Allow guest play, prompt to register to save stats
   • Guest games count for global stats but not personal leaderboards

2. Game history retention?

   • Decision: Keep events forever (they're small, ~500 bytes each)
   • Implement archival to cold storage after 1 year if needed

3. Replay visibility?

   • Decision: Private by default, shareable via link
   • Future: Public games opt-in

4. CPU games count for leaderboards?

   • Decision: Yes, but separate "vs humans only" leaderboard later

5. Multi-region?

   • Decision: Not for V2, single region is fine for card game latency
   • Revisit if user base grows significantly

---

How to Use These Documents

Each V2_XX_*.md document is designed to be:

1. Self-contained - Has all context needed to implement that slice
2. Agent-ready - Can be given to a Claude agent as the primary context
3. Testable - Includes acceptance criteria and test requirements
4. Incremental - Can be implemented and shipped independently (respecting dependencies)

Workflow:

1. Pick a document based on current phase
2. Start a new Claude session with that document as context
3. Implement the slice
4. Run tests specified in the document
5. PR and merge
6. Move to next slice

---

Next Steps

1. Review all V2 documents
2. Set up PostgreSQL locally for development
3. Start with V2_01_EVENT_SOURCING.md
4. Implement rate limiting from V2_07_PRODUCTION.md early (security)