A mobile-first web implementation of the classic card game 31 (also known as Scat or Blitz). Build the highest same-suit hand — a score of 31 wins instantly.
Live at 31.spoole.dev · Built by spoole50
Objective: Get the highest total value of cards in the same suit. A score of 31 is an instant win.
Card values:
- Ace — 11 points
- King, Queen, Jack — 10 points each
- Number cards — face value (2–10)
Special cases:
- Three Aces = 31 (instant win for holder — everyone else loses a life)
- Getting 31 = instant win for the round
Gameplay:
- Each player is dealt 3 cards and receives 3 lives
- On your turn: draw from the deck or discard pile, then discard one card
- Knock to trigger the final round — all other players get one last turn
- The player with the lowest hand score loses a life
- Ties for lowest both lose a life
- Last player with lives remaining wins
- Local game — play against up to 7 AI opponents, no account needed
- Pass-and-play — multiple human players share a device with a hand-reveal handoff screen
- AI difficulty levels — Easy, Medium, Hard, Expert
- Optional turn timer — 45-second countdown per turn (toggle in setup)
- Online multiplayer — create or join tables with a 6-character invite code,
or share a link (
/online?code=ABC123); the host can start a rematch from the results screen - Round summary — after every round, everyone's final hand, score and who
lost a life (backed by the
last_roundfield in the game state) - Real-time via Socket.IO — server pushes every move; long-polling in production (App Runner has no WebSockets), real WebSockets locally
- Card animations — spring flip-in, draw pop, Framer Motion throughout
- 31 celebration — suit-symbol confetti burst on instant win
- Dark casino theme — mobile-first Tailwind CSS, gold-on-felt design
| Layer | Technology |
|---|---|
| Frontend | React 18, Vite 5, Tailwind CSS 3, Zustand 4, Framer Motion 11, React Router v6 |
| Realtime | socket.io-client 4, 10 s heartbeat, reconnect on drop |
| Backend | Python 3.11, FastAPI, python-socketio 5, uvicorn |
| State | In-memory, single process (a redeploy drops live games) |
| Hosting | AWS Amplify (frontend) · AWS App Runner (backend) |
| Container | Docker (linux/amd64), UvicornWorker |
- Python 3.11+
- Node.js 18+ —
.nvmrcpins 24; with fnm or nvm installed,cdinto the repo and the right version is selected for you - Docker is not required (see DEPLOYMENT.md)
python3 -m venv .venv
.venv/bin/pip install -r backend/requirements.txt
npm installnpm run dev # uvicorn on :8000 + Vite on :3000, togetherOr separately:
npm run dev:backend # uvicorn main:app --reload --port 8000
npm run dev:frontend # vite on :3000Vite proxies /api and /socket.io to http://localhost:8000, so no env var is
needed locally. http://localhost:3000 is always allowed by the backend's CORS
allowlist.
# Ctrl+C in the terminal, or kill the backend by port:
lsof -ti :8000 | xargs killcurl http://localhost:8000/api/health
# {"status":"healthy","version":"2.0.0","games":0,"tables":0,"connected_players":0}31/
├── backend/
│ ├── main.py # FastAPI app + socketio ASGI mount
│ ├── game_logic.py # Core rules, GameState, Player, Card
│ ├── table_logic.py # Table / lobby management
│ ├── core/
│ │ ├── config.py # CORS allowlist (ALLOWED_ORIGINS)
│ │ ├── limits.py # Per-IP create rate limit + capacity caps
│ │ ├── socket.py # Shared AsyncServer singleton
│ │ └── store.py # In-memory GameStore + socket ↔ player map
│ ├── api/
│ │ ├── game_router.py # Local game REST endpoints
│ │ ├── table_router.py # Multiplayer table REST endpoints
│ │ └── socket_handlers.py# All WebSocket events
│ ├── ai/
│ │ └── engine.py # AI strategy (4 difficulty levels)
│ ├── utils/
│ │ └── serializers.py # Game state → JSON (hides opponents' hands)
│ ├── tests/test_api.py # pytest suite (REST, CORS, limits, seat tokens)
│ └── scripts/socket_smoke.py # Socket.IO smoke test against a live server
├── .github/workflows/ # ci.yml (tests) · deploy-backend.yml (OIDC → App Runner)
├── frontend/
│ ├── index.html # Vite root
│ ├── vite.config.js
│ ├── tailwind.config.js
│ └── src/
│ ├── main.jsx # ReactDOM entry
│ ├── App.jsx # React Router v6 routes
│ ├── lib/socket.js # Socket.IO singleton
│ ├── store/
│ │ └── gameStore.js # Zustand store (local + online slices)
│ ├── pages/
│ │ ├── MainMenu.jsx
│ │ ├── LocalSetup.jsx
│ │ ├── LocalGame.jsx
│ │ ├── OnlineLobby.jsx
│ │ ├── TableLobby.jsx
│ │ └── GameRoom.jsx
│ └── components/
│ ├── GameBoard.jsx # Main game view (pass-and-play + celebration)
│ ├── Card.jsx # Animated playing card
│ ├── PlayerHand.jsx # Hand with draw-pop detection
│ ├── DiscardPile.jsx
│ ├── TurnTimer.jsx # SVG ring countdown
│ ├── OpponentStrip.jsx
│ ├── GameLog.jsx
│ ├── RulesModal.jsx
│ └── … # overlays, toast, game-over screen
├── docker-compose.yml
└── amplify.yml
| Method | Path | Description |
|---|---|---|
| POST | /api/games |
Create a new local game |
| GET | /api/games/{id} |
Get game state |
| POST | /api/games/{id}/draw |
Draw from deck or discard pile |
| POST | /api/games/{id}/discard |
Discard a card |
| POST | /api/games/{id}/knock |
Knock to end the round |
| POST | /api/games/{id}/timeout |
Force-skip the current turn (local timer) |
| POST | /api/games/{id}/ai-turn |
Process AI player turn |
| GET | /api/health |
Server health + stats |
| Method | Path | Description |
|---|---|---|
| POST | /api/tables |
Create a table |
| GET | /api/tables · /api/tables/public |
List public tables |
| GET | /api/tables/{id} |
Get table info |
| POST | /api/tables/join |
Join by invite_code or table_id |
| POST | /api/tables/{id}/start |
Start game (host only) |
| POST | /api/tables/{id}/restart |
Restart a finished game (host only) |
| POST | /api/tables/{id}/leave |
Leave table |
| POST | /api/tables/{id}/add-ai |
Add AI player (host only) |
| GET | /api/player/{id}/table |
Get a player's current table |
There is deliberately no REST endpoint for reading game state or submitting game actions. Both used to exist and both were unauthenticated — the read returned any player's hand to any caller, and the write accepted moves as any player. Gameplay goes exclusively through Socket.IO, which verifies the socket session owns the claimed player and emits per-player payloads with opponents' hands hidden. Clients receive state on join and after every action.
| Direction | Event | Description |
|---|---|---|
| → server | join_table |
Join a table room (needs the seat player_token) |
| → server | leave_table |
Leave a table room |
| → server | game_action |
draw / discard / knock |
| → server | ping |
Heartbeat (every 10 s) |
| ← client | table_updated |
Lobby / table state changed |
| ← client | game_updated |
Game state after any action |
| ← client | player_disconnected |
A player dropped |
| ← client | turn_timeout |
Turn was auto-skipped |
| ← client | error |
Action rejected with reason |
See DEPLOYMENT.md for the full AWS guide.
Infrastructure:
- Frontend: AWS Amplify — auto-deploys on push to
main(npm run build → build/) - Backend: AWS App Runner (
us-east-1) — deploys from ECR on image push - Single uvicorn process, App Runner pinned to one instance (state is in memory)
App Runner does not scale to zero — it keeps 0.5 GB provisioned at all times and
bills ~$2.50/month even with no traffic. That is still the cheapest AWS option for this
backend (App Runner is closed to new AWS customers but fully supported for this
account; see DEPLOYMENT.md).
The way to shrink what the backend has to do is to make local play client-side
(bigger change, removes the backend from the hot path). Every local single-player action currently round-trips to /api/games/*, so even
offline-style play needs the paid server running. Porting game_logic.py +
ai/engine.py to JS would make local games run entirely in the browser (static,
free on Amplify) and leave the backend needed only for online multiplayer.