b8bc432175
Batched remaining harness tasks (27-30, 33):
Task 27 — Artifact capture on failure: screenshots, HTML snapshots,
game state JSON, and console error tails are captured into
tests/soak/artifacts/<run-id>/ when a scenario throws. Successful
runs get a summary.json. Old runs (>7d) are pruned on startup.
Task 28 — Graceful shutdown: first SIGINT/SIGTERM flips the abort
signal (scenarios finish current turn then unwind). 10s after, a
hard-kill fires if cleanup hangs. Double Ctrl-C = immediate exit.
Exit codes: 0 success, 1 errors, 2 interrupted.
Task 29 — Periodic health probes: every 30s GET /health against the
target server. Three consecutive failures abort the run with
health_fatal, preventing staging outages from being misattributed
to harness bugs. Corrected endpoint from /api/health to /health
per server/routers/health.py.
Task 30 — Smoke test script: tests/soak/scripts/smoke.sh, a 60s
end-to-end canary that health-probes the target, seeds if needed,
and runs one minimal populate game.
Task 33 — Version bump to v3.3.4: both index.html footers (was
v3.1.6), new footer added to admin.html (had none), pyproject.toml.
Also fixes discovered during stress testing:
- SessionPool sets baseURL on all contexts so relative goto('/')
resolves correctly between games (was "invalid URL" error)
- RoomCoordinator key is now unique per game-start (Date.now
suffix) so Deferred promises don't carry stale room codes from
previous games
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Golf Card Game
A real-time multiplayer 6-card Golf card game with AI opponents, smooth anime.js animations, and extensive house rules support.
Features
- Real-time Multiplayer: 2-6 players via WebSocket
- AI Opponents: 8 unique CPU personalities with distinct play styles
- House Rules: 15+ optional rule variants
- Smooth Animations: Anime.js-powered card dealing, drawing, swapping, and flipping
- User Accounts: Registration, login, email verification
- Stats & Leaderboards: Player statistics, win rates, and rankings
- Game Replay: Review completed games with full playback
- Admin Tools: User management, game moderation, system monitoring
- Event Sourcing: Full game history stored for replay and analysis
- Production Ready: Docker, systemd, nginx, rate limiting, Sentry integration
Quick Start
# Install dependencies
pip install -r server/requirements.txt
# Run the server
python server/main.py
# Visit http://localhost:8000
For full installation instructions (Docker, production deployment, etc.), see INSTALL.md.
How to Play
6-Card Golf is a card game where you try to get the lowest score across multiple rounds (holes).
- Each player has 6 cards in a 2x3 grid (most start face-down)
- On your turn: draw a card, then swap it with one of yours or discard it
- Column pairs (same rank top & bottom) score 0 points — very powerful!
- When any player reveals all 6 cards, everyone else gets one final turn
- Lowest total score after all rounds wins
For detailed rules, card values, and house rule explanations, see the in-game Rules page or server/RULES.md.
AI Personalities
| Name | Style | Description |
|---|---|---|
| Sofia | Calculated & Patient | Conservative, low risk |
| Maya | Aggressive Closer | Goes out early |
| Priya | Pair Hunter | Holds cards hoping for pairs |
| Marcus | Steady Eddie | Balanced, consistent |
| Kenji | Risk Taker | High variance plays |
| Diego | Chaotic Gambler | Unpredictable |
| River | Adaptive Strategist | Adjusts to game state |
| Sage | Sneaky Finisher | Aggressive end-game |
House Rules
The game supports 15+ optional house rules including:
- Flip Modes - Standard, Speed Golf (must flip after discard), Suspense (optional flip near endgame)
- Point Modifiers - Super Kings (-2), Ten Penny (10=1), Lucky Swing Joker (-5)
- Bonuses & Penalties - Knock bonus/penalty, Underdog bonus, Tied Shame, Blackjack (21->0)
- Joker Variants - Standard, Eagle Eye (paired Jokers = -8)
See the in-game Rules page or server/RULES.md for complete explanations.
Development
Project Structure
golfgame/
├── server/ # Python FastAPI backend
│ ├── main.py # HTTP routes, WebSocket server, lifespan
│ ├── game.py # Core game logic, state machine
│ ├── ai.py # CPU opponent AI with timing/personality
│ ├── handlers.py # WebSocket message handlers
│ ├── room.py # Room/lobby management
│ ├── config.py # Environment configuration (pydantic)
│ ├── constants.py # Card values, game constants
│ ├── auth.py # Authentication (JWT, passwords)
│ ├── logging_config.py # Structured logging setup
│ ├── simulate.py # AI-vs-AI simulation runner
│ ├── game_analyzer.py # Decision analysis CLI
│ ├── score_analysis.py # Score distribution analysis
│ ├── routers/ # FastAPI route modules
│ │ ├── auth.py # Login, signup, verify endpoints
│ │ ├── admin.py # Admin management endpoints
│ │ ├── stats.py # Statistics & leaderboard endpoints
│ │ ├── replay.py # Game replay endpoints
│ │ └── health.py # Health check endpoints
│ ├── services/ # Business logic layer
│ │ ├── auth_service.py # User authentication
│ │ ├── admin_service.py # Admin tools
│ │ ├── stats_service.py # Player statistics & leaderboards
│ │ ├── replay_service.py # Game replay functionality
│ │ ├── game_logger.py # PostgreSQL game move logging
│ │ ├── spectator.py # Spectator mode
│ │ ├── email_service.py # Email notifications (Resend)
│ │ ├── recovery_service.py # Account recovery
│ │ └── ratelimit.py # Rate limiting
│ ├── stores/ # Data persistence layer
│ │ ├── event_store.py # PostgreSQL event sourcing
│ │ ├── user_store.py # User persistence
│ │ ├── state_cache.py # Redis state caching
│ │ └── pubsub.py # Pub/sub messaging
│ ├── models/ # Data models
│ │ ├── events.py # Event types for event sourcing
│ │ ├── game_state.py # Game state representation
│ │ └── user.py # User data model
│ ├── middleware/ # Request middleware
│ │ ├── security.py # CORS, CSP, security headers
│ │ ├── request_id.py # Request ID tracking
│ │ └── ratelimit.py # Rate limiting middleware
│ ├── RULES.md # Rules documentation
│ └── test_*.py # Test files
│
├── client/ # Vanilla JS frontend
│ ├── index.html # Main game page
│ ├── app.js # Main game controller
│ ├── card-animations.js # Unified anime.js animation system
│ ├── card-manager.js # DOM management for cards
│ ├── animation-queue.js # Animation sequencing
│ ├── timing-config.js # Centralized timing configuration
│ ├── state-differ.js # Diff game state for animations
│ ├── style.css # Styles (NO card transitions)
│ ├── admin.html # Admin panel
│ ├── admin.js # Admin panel interface
│ ├── admin.css # Admin panel styles
│ ├── replay.js # Game replay viewer
│ ├── leaderboard.js # Leaderboard display
│ └── ANIMATIONS.md # Animation system documentation
│
├── scripts/ # Helper scripts
│ ├── install.sh # Interactive installer
│ ├── dev-server.sh # Development server launcher
│ └── docker-build.sh # Docker image builder
│
├── docs/ # Architecture documentation
│ ├── ANIMATION-FLOWS.md # Animation flow diagrams
│ ├── v2/ # V2 architecture docs
│ └── v3/ # V3 feature & refactoring docs
│
├── tests/e2e/ # End-to-end tests (Playwright)
├── docker-compose.dev.yml # Dev Docker services (PostgreSQL + Redis)
├── docker-compose.prod.yml # Production Docker setup
├── Dockerfile # Container definition
├── pyproject.toml # Python project metadata
├── INSTALL.md # Installation & deployment guide
├── CLAUDE.md # Project context for AI assistants
└── README.md
Running Tests
# All server tests
cd server && pytest -v
# Specific test files
pytest test_game.py test_ai_decisions.py test_handlers.py test_room.py -v
# With coverage
pytest --cov=. --cov-report=term-missing
AI Simulation
# Run 500 games and check dumb move rate
python server/simulate.py 500
# Detailed single game output
python server/simulate.py 1 --detailed
# Compare rule presets
python server/simulate.py 100 --compare
# Analyze AI decisions for blunders
python server/game_analyzer.py blunders
# Score distribution analysis
python server/score_analysis.py 100
AI Performance
From testing (1000+ games):
- 0 blunders detected in simulation
- Median score: 12 points
- Score range: -4 to 34 (typical)
- Personalities influence style without compromising competence
Technology Stack
- Backend: Python 3.11+, FastAPI, WebSockets
- Frontend: Vanilla HTML/CSS/JavaScript, anime.js (animations)
- Database: PostgreSQL (event sourcing, auth, stats, game logs)
- Cache: Redis (state caching, pub/sub)
- Testing: pytest, Playwright (e2e)
- Deployment: Docker, systemd, nginx
License
GPL-3.0-or-later — see LICENSE for the full text.