# Production-Ready Lô Tô Game — Full Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build a full-stack multiplayer Lô Tô game (Node.js backend + React frontend) that is production-ready, deployable to Zalo Mini Apps, with robust testing, authentication, real-time gameplay, and full economy/social features.

**Architecture:** Server-authoritative WebSocket game server (Socket.io) with React SPA frontend, using PostgreSQL for persistence and Redis for real-time state/rate limiting. All game logic validated server-side; client uses optimistic UI.

**Tech Stack:**
- Backend: Node.js, Express, Socket.io, JSON Web Tokens (JWT), PostgreSQL (Supabase/Neon), Redis (Upstash)
- Frontend: React 18, Vite, Socket.io-client, Framer Motion, Zustand (state), Tailwind CSS (styling)
- Testing: Jest (unit), Cypress (E2E multi-player)
- Deployment: Docker, Vercel (frontend), Railway/Render (backend), GitHub Actions (CI)
- Auth: JWT, Zalo OAuth (Phase 2), anonymous temp users (Phase 1)

---

## Pre-Implementation Setup

Before any tasks, ensure environment:

- Create directory structure for frontend (`client/`) and backend (`server/`)
- Initialize Git repository (if not already)
- Create `.gitignore` (Node, React, VSCode,OS, env files)
- Set up root `docker-compose.yml` for local DB+Redis
- Create `.env.example` with all required env vars: DB URLs, JWT secret, Redis URL, etc.
- Set up root `package.json` workspaces or separate package.json server/client
- Configure ESLint + Prettier for consistency

---

## Phase 1: Foundation (Backend Core) — 2 weeks

### Task 1: Initialize Backend Project & Docker Compose

**Files:**
- Create: `server/package.json`
- Create: `server/.env.example`
- Create: `server/.eslintrc.js`
- Create: `server/README.md`
- Create: `docker-compose.yml` at repo root
- Create: `.gitignore`

- [ ] **Step 1: Write failing test** — not applicable (setup task)
- [ ] **Step 2: Create server/package.json** with dependencies: `express`, `socket.io`, `pg`, `ioredis`, `jsonwebtoken`, `uuid`, `dotenv`, `winston`, `cors`, `helmet`
- [ ] **Step 3: Create docker-compose.yml** with services: `postgres` (image: postgres:15), `redis` (image: redis:7)
- [ ] **Step 4: Create .env.example** listing all env vars (DATABASE_URL, REDIS_URL, JWT_SECRET, PORT=3001, NODE_ENV=development)
- [ ] **Step 5: Create server README** with setup instructions
- [ ] **Step 6: Commit** with message "feat: initialize backend project and docker compose"

### Task 2: Database Schema Migration

**Files:**
- Create: `server/db/migrations/001_initial_schema.sql`
- Create: `server/db/index.js` ( connects to PostgreSQL using `pg` or `supabase` client)
- Create: `server/db/redisClient.js` (connects to Redis)

- [ ] **Step 1: Write failing test** — create `server/db/schema.test.js` that imports the schema file and checks that all tables exist using raw SQL introspection (skip in CI if DB not up)
- [ ] **Step 2: Write SQL migration** with all tables and indexes exactly as spec (users, rooms, room_players, coin_transactions, game_history)
- [ ] **Step 3: Write db/index.js** that exports pool with `DATABASE_URL` connection; include `query` helper that logs slow queries (>100ms)
- [ ] **Step 4: Write db/redisClient.js** that creates Redis client from `REDIS_URL`, exports with `get`/`set`/`sadd`/`zadd` wrappers
- [ ] **Step 5: Run test** — ensure migration SQL can be applied (docker compose up -d; psql -f migration)
- [ ] **Step 6: Commit** "feat: database schema and clients"

### Task 3: JWT Auth Service (Anonymous)

**Files:**
- Create: `server/services/auth.js`
- Create: `server/middleware/auth.js`
- Create: `server/routes/auth.js`
- Modify: `server/index.js` (or `server/app.js`) to register auth routes

- [ ] **Step 1: Write failing test** — `server/services/auth.test.js`:
  - test `createAnonymousUser()` returns a JWT and creates user record with temp_id
  - test `authenticateJWT()` validates token and returns user payload
- [ ] **Step 2: Implement auth.service**:
  - `generateTempUserId()` — UUID v4
  - `createAnonymousUser()` — INSERT into users (temp_id, coins=1000) RETURNING id, temp_id, coins; sign JWT with payload `{ userId, tempId, type: 'anonymous' }`
  - `verifyToken(token)` — verify JWT secret, return payload
- [ ] **Step 3: Implement auth.middleware** that extracts Bearer token, calls verifyToken, attaches `req.user`
- [ ] **Step 4: Implement auth.route**:
  - POST `/api/auth/anonymous` → creates anonymous account, returns `{ token, user: { id, coins } }`
  - GET `/api/auth/me` → returns user from token
- [ ] **Step 5: Wire up server** to use routes and middleware
- [ ] **Step 6: Run tests** — pass
- [ ] **Step 7: Commit** "feat: anonymous JWT auth"

### Task 4: Socket.io Server Setup

**Files:**
- Create: `server/socket/socketServer.js`
- Create: `server/socket/handlers/roomHandlers.js`
- Create: `server/socket/handlers/gameHandlers.js`
- Modify: `server/index.js` to initialize Socket.io and attach handlers

- [ ] **Step 1: Write failing test** — `server/socket/socketServer.test.js` using `socket.io-client` to connect, emit `create_room`, expect `room_created` event (mock DB)
- [ ] **Step 2: Implement socketServer.js**:
  - `setupSocket(server)` attaches Socket.io to HTTP server
  - uses `socket.use(authMiddleware)` to authenticate JWT
  - registers namespaces (none, default)
- [ ] **Step 3: Implement roomHandlers.js**:
  - `onCreateRoom(socket, data)` validates betAmount, maxPlayers, highlightSeconds; generates room code; creates room record; joins socket to room; emits `room_created`
  - `onJoinRoom(socket, {roomCode})` validates code; adds player to room_players; joins socket room; emits `room_joined` with state
  - `onReady(socket)` marks player ready; if all ready, transitions to `playing` after countdown
- [ ] **Step 4: Implement gameHandlers.js** (stubs):
  - `onPlaceGrain` — validations (server-authoritative) will be added later
  - `onCallKinh` — stub: push to Redis claims set
  - `onChat` — broadcast to room
- [ ] **Step 5: Wire in socketServer to index.js**
- [ ] **Step 6: Run test** — pass
- [ ] **Step 7: Commit** "feat: socket.io server and room/game handlers"

### Task 5: Rate Limiting Middleware

**Files:**
- Create: `server/middleware/rateLimit.js`

- [ ] **Step 1: Write failing test** — `server/middleware/rateLimit.test.js`:
  - Simulate 10 requests from same user within second; first N allowed, rest blocked with 429
  - TTL expiration allows after 1s
- [ ] **Step 2: Implement rateLimit middleware**:
  - Uses Redis key `rate_limit:{userId}:{action}` with INCR and EXPIRE 1s
  - Allows max 10 requests per second per action type (grain_placement, call_kinh, chat)
  - Returns 429 with JSON `{ error: 'rate_limited' }` if exceeded
  - Attachable to socket.io via `socket.use(...)`
- [ ] **Step 3: Apply rate limiting** to `place_grain`, `call_kinh`, `chat` events in socket handlers
- [ ] **Step 4: Run tests** — pass
- [ ] **Step 5: Commit** "feat: rate limiting per user action"

### Task 6: Balance Reservation at Join

**Files:**
- Modify: `server/socket/handlers/roomHandlers.js` (join_room)
- Create: `server/services/coinService.js`
- Create: `server/services/coinService.test.js`

- [ ] **Step 1: Write failing test** — test `reserveBet(userId, roomBet)` deducts from users.coins and logs coin_transaction type=BET_PLACED with negative amount; test failure when insufficient coins
- [ ] **Step 2: Implement coinService**:
  - `reserveBet(userId, amount)` — atomic: UPDATE users SET coins = coins - amount WHERE id=$1 AND coins >= amount; if row count 0 throw insufficient; then INSERT coin_transaction (type=BET_PLACED, amount=-amount, balance_after = (SELECT coins FROM users WHERE id=$1))
  - `refundBet(userId, amount)` — opposite (used on leave before start)
  - `applyWin(userId, amount, roomId)` — add coins, log KINH_WON
  - `applyPenalty(userId, amount, roomId)` — subtract coins, log KINH_PENALTY
- [ ] **Step 3: Wire join_room** to call `reserveBet` when player joins; if fails, emit error and reject join
- [ ] **Step 4: Run tests** — pass
- [ ] **Step 5: Commit** "feat: coin reservation on room join"

---

## Phase 2: Core Gameplay Engine — 2 weeks

### Task 7: Number Draw Engine

**Files:**
- Create: `server/services/drawEngine.js`
- Create: `server/services/drawEngine.test.js`
- Modify: `server/socket/handlers/gameHandlers.js` (add `startGame`)

- [ ] **Step 1: Write failing test** — test `shuffleNumbers()` returns array of 90 unique numbers; test `drawNext()` returns number not previously drawn
- [ ] **Step 2: Implement drawEngine**:
  - `createDeck()` returns shuffled numbers 1..90 using Fisher-Yates
  - `DrawSession` class: holds remaining deck, drawn array, current index. Method `drawNext()` returns next number, stores in drawn array with timestamp
- [ ] **Step 3: Implement `startGame(roomId)` handler**:
  - Fetch room players; verify all ready or owner forced start
  - Create DrawSession for room (store in Redis: `room:{roomId}:draw_state` = JSON with deck)
  - Set room status = 'playing'; broadcast `game_start` with empty drawnNumbers
  - Begin async loop: for each number, `setTimeout` highlightSeconds*1000, then emit `number_drawn` and `highlight_end`
- [ ] **Step 4: Run tests** — pass
- [ ] **Step 5: Commit** "feat: number draw engine with broadcast"

### Task 8: Rice Grain Placement Validation

**Files:**
- Create: `server/services/boardService.js`
- Create: `server/services/boardService.test.js`
- Modify: `server/socket/handlers/gameHandlers.js` (onPlaceGrain)

- [ ] **Step 1: Write failing test** — test `canPlaceGrain(userId, row, col, drawnNumbers)` returns false if column's number not in drawnNumbers; true if drawn; also check max 5 grains per row
- [ ] **Step 2: Implement boardService**:
  - `getNumberForCell(row, col)` returns number (1–90) based on standard Lô Tô card layout (3 rows × 9 cols, 5 numbers per row distributed by decades)
  - `isNumberDrawn(num, drawnNumbers)` — includes in array check
  - `canPlaceGrain(userId, row, col, drawnNumbers, roomPlayers)` — ensures user has not exceeded 5 grains per row; cell not already occupied by that user; number drawn; bet reserved sufficient
  - `placeGrain(userId, row, col)` — records grain placement (in Redis set `room:{roomId}:player:{userId}:grains` serialized) and broadcast to room
- [ ] **Step 3: in onPlaceGrain**, validate with boardService; if valid, update Redis and broadcast `grain_placed` event with position; if invalid, emit error
- [ ] **Step 4: Run tests** — pass
- [ ] **Step 5: Commit** "feat: rice grain placement validation"

### Task 9: Concurrent Kinh Handling

**Files:**
- Modify: `server/socket/handlers/gameHandlers.js` (onCallKinh)
- Create: `server/services/kinhService.js`
- Create: `server/services/kinhService.test.js`

- [ ] **Step 1: Write failing test** — test `validateKinh(userId, roomId)` returns true if all rows that have grains fully match drawnNumbers; false otherwise
- [ ] **Step 2: Implement `validateKinh`**:
  - Get user's grains from Redis; compute rows where they have exactly 5 grains; check every grain's number is in drawnNumbers
  - Returns object `{ valid: boolean, rowsCompleted: number[] }`
- [ ] **Step 3: Implement onCallKinh**:
  - When received, add to Redis sorted set `room:{roomId}:kinh_claims` with score=Date.now()
  - Broadcast `kinh_claim` to room so UI shows pending badge
  - Do not respond immediately; wait for freeze window end
- [ ] **Step 4: Modify draw engine**:
  - After `highlight_end` emitted, set a short freeze timeout (500ms)
  - After freeze, collect all userIds from Redis sorted set (score within window); clear set; process all claims via `processKinhClaims(roomId, claims)`
- [ ] **Step 5: Implement processKinhClaims**:
  - For each claimant, run `validateKinh`
  - Separate into validWinners and invalidClaimants
  - Compute totalPot = sum of all bets (roomBet * numPlayers)
  - Compute reward per valid = totalPot / validCount (integer math; any remainder left in pot? Could add to next round or house. We'll do integer division, remainder stays with house for simplicity)
  - For each invalid, penalty = betAmount to *every other player* in room (including other invalids). Implement loop: for each invalid `p`, for each other player `q` in room_players, transfer `betAmount` from p to q using coinService
  - For each valid, reward = their share (already computed) added to balance via coinService
  - Update room status to 'settling'; then 'settled' after DB updates
  - Broadcast `game_settled` with full results (including pre/post balances)
- [ ] **Step 6: Run tests** — pass (use unit tests to validate math; integration will test end-to-end)
- [ ] **Step 7: Commit** "feat: concurrent Kinh verification and settlement"

---

## Phase 3: Frontend Core — 2 weeks

### Task 10: Initialize React Frontend with Vite

**Files:**
- Create: `client/package.json`
- Create: `client/vite.config.js`
- Create: `client/index.html`
- Create: `client/src/main.jsx`
- Create: `client/src/App.jsx`
- Create: `client/tailwind.config.js` (or use plain CSS per retro theme)
- Create: `client/.env.example`

- [ ] **Step 1: Create client/package.json** with deps: `react`, `react-dom`, `vite`, `socket.io-client`, `framer-motion`, `zustand`, `axios`, `tailwindcss`
- [ ] **Step 2: Create vite.config.js** for React, set base for Zalo Mini App later (`base: './'`), proxy API to backend for dev (`server.proxy`)
- [ ] **Step 3: Create index.html** simple root div
- [ ] **Step 4: Create main.jsx** ReactDOM.render into #root
- [ ] **Step 5: Create App.jsx** with basic routing (Lobby vs Game) using React state for now
- [ ] **Step 6: Create .env.example** with VITE_API_URL, VITE_WS_URL
- [ ] **Step 7: Commit** "feat: initialize React frontend with Vite"

### Task 11: Authentication Context & Login UI

**Files:**
- Create: `client/src/contexts/AuthContext.jsx`
- Create: `client/src/hooks/useAuth.js`
- Create: `client/src/components/Auth/AuthModal.jsx`
- Create: `client/src/components/Auth/LoginButton.jsx`
- Modify: `client/src/App.jsx` to use AuthContext and show login UI

- [ ] **Step 1: Write failing test** — `client/src/contexts/AuthContext.test.jsx` with Jest Testing Library: test that after login, context has token and user; test localStorage persistence
- [ ] **Step 2: Implement AuthContext**:
  - State: `user` (null or {id, coins}), `token` (string), `loading`
  - Effect on mount: check localStorage for token; if present, call `/api/auth/me` to validate; else clear
  - `loginAnonymous()` calls POST `/api/auth/anonymous`, saves token+user to localStorage, updates state
  - `logout()` clears state and localStorage
- [ ] **Step 3: Implement LoginButton** that triggers `loginAnonymous`; also placeholder Zalo button (disabled behind flag)
- [ ] **Step 4: Implement AuthModal** that shows login options, closes after login
- [ ] **Step 5: Wire App.jsx**: if not authenticated, show login modal; else show main app (lobby placeholder)
- [ ] **Step 6: Run tests** — pass
- [ ] **Step 7: Commit** "feat: anonymous auth context and UI"

### Task 12: WebSocket Hook & Socket Context

**Files:**
- Create: `client/src/hooks/useWebSocket.js`
- Create: `client/src/contexts/GameContext.jsx`
- Create: `client/src/services/socketService.js`

- [ ] **Step 1: Write failing test** — `client/src/hooks/useWebSocket.test.js`: mock socket.io-client; test that on connection, state is connected; on event, handler called
- [ ] **Step 2: Implement socketService.js**:
  - Singleton that creates `socket` instance from `io()` with auth token
  - Methods: `on(event, handler)`, `emit(event, payload)`, `disconnect()`
  - Auto-reconnect logic
- [ ] **Step 3: Implement useWebSocket** hook that provides `socket` object via context
- [ ] **Step 4: Implement GameContext**:
  - State: `room`, `players`, `gameState` ('lobby','playing','frozen','settled'), `currentNumber`, `myGrains`, etc.
  - Socket event listeners: `room_joined`, `player_joined`, `number_drawn`, `highlight_end`, `kinh_claim`, `game_settled`, `balance_update`, `error`
  - Methods: `createRoom`, `joinRoom`, `ready`, `placeGrain`, `callKinh`, `sendChat`, `leave`
- [ ] **Step 5: Run tests** — pass
- [ ] **Step 6: Commit** "feat: WebSocket hook and game context"

### Task 13: Lobby & Room Management UI

**Files:**
- Create: `client/src/components/Lobby/LobbyList.jsx`
- Create: `client/src/components/Lobby/RoomCard.jsx`
- Create: `client/src/components/Lobby/CreateRoomModal.jsx`
- Modify: `client/src/App.jsx` to show lobby when authenticated

- [ ] **Step 1: Write failing test** — `client/src/components/Lobby/LobbyList.test.jsx`: test that room cards display bet amount, player count; test join button calls joinRoom
- [ ] **Step 2: Implement CreateRoomModal** with form fields: bet amount (input), max players (select 2-8), highlight seconds (select 1-5). Submits to `createRoom` from GameContext.
- [ ] **Step 3: Implement RoomCard** to show room code, bet, players count, status; join button disabled if full or started
- [ ] **Step 4: Implement LobbyList** that fetches public rooms from `/api/rooms/public` (backend stub needed later) or via socket event `public_rooms` (we'll add that to backend later). For now, mock data; later will wire to backend.
- [ ] **Step 5: Wire App.jsx** to show LobbyList after login; show CreateRoomModal button
- [ ] **Step 6: Run tests** — pass
- [ ] **Step 7: Commit** "feat: lobby UI and room creation"

---

## Phase 4: Core Gameplay Frontend — 2 weeks

### Task 14: Lotto Card & Board

**Files:**
- Create: `client/src/components/Game/LottoCard.jsx`
- Create: `client/src/utils/cardPositions.js`
- Modify: `client/src/components/Game/GameBoard.jsx` (to be created)

- [ ] **Step 1: Write failing test** — `client/src/components/Game/LottoCard.test.jsx`: test that grid has 3 rows, 9 cols; test clicking cell triggers `placeGrain`; test grains display as placed
- [ ] **Step 2: Implement cardPositions.js** with `getNumberForCell(row, col)` (0-indexed rows 0-2, cols 0-8). Rules: Column 0 = numbers 1-9; column 1 = 10-19; ... column 8 = 81-90? Actually Lô Tô: 9 columns represent tens: 1-9,10-19,...,80-90. Each column has 3 rows, but only 5 numbers per row across columns. Standard layout: Each row contains 5 numbers placed in specific column positions based on decade. We need precise mapping. Quick reference: traditional Lô Tô card:
  - Columns: 1 (1-9), 2 (10-19), 3 (20-29), 4 (30-39), 5 (40-49), 6 (50-59), 7 (60-69), 8 (70-79), 9 (80-90)
  - Rows: top, middle, bottom. Each row has 5 numbers; the distribution across columns follows rules: each row includes exactly 5 numbers from 5 different columns. There are standard patterns but we can simplify: randomly assign 5 numbers (from the column's range) to each row, ensuring each column used at least once across rows? For simplicity, we can predefine a fixed pattern for all cards: each card identical layout. Let's define a static mapping array `CELL_NUMBERS[3][9]` where each cell has a number (1-90) or null. Only 15 cells are numbers; others empty visual. We'll create a deterministic layout (same for all players) to avoid needing dynamic generation. We'll hardcode a valid Lô Tô card pattern: e.g., 
Row1: 1,11,21,31,41 at columns 1,2,3,4,5; others empty.
Row2: 51,61,71,81,91? Wait 91 doesn't exist. Let's design properly: We need 5 numbers per row across 9 columns; each column appears at most once per row. Use this pattern (just an example):
Row1: col0=1, col1=11, col2=25, col3=33, col4=44, others null
Row2: col0=5, col1=17, col2=28, col4=49, col6=62
Row3: col1=20, col3=39, col5=58, col7=79, col8=90
We'll make a specific valid layout and hardcode it. It's not random; all players have same card pattern. That's fine for MVP.
Implement `getNumberForCell(row, col)` returns that hardcoded number or null.
- [ ] **Step 3: Implement LottoCard component**:
  - Renders a 3x9 grid using CSS grid.
  - For each cell: if number exists, clickable area; if null, empty placeholder with retro styling.
  - Shows rice grain overlay if cell is in `grains` set (from GameContext)
  - If cell's number is in `drawnNumbers`, highlight with CSS class
  - onClick calls `placeGrain(row, col)`
- [ ] **Step 4: Implement GameBoard**:
  - Contains LottoCard, NumberBag animation, current number display, Kinh button, players panel
  - Uses Framer Motion for NumberBag (shake) when number being drawn
- [ ] **Step 5: Run tests** — pass
- [ ] **Step 6: Commit** "feat: Lotto card and game board UI"

### Task 15: Framer Motion Animations

**Files:**
- Modify: `client/src/components/Game/NumberBag.jsx` (new file)
- Modify: `client/src/components/Game/RiceGrain.jsx` (new file)
- Modify: `client/src/styles/retroTheme.js`

- [ ] **Step 1: Write failing test** (visual, manual) — skip unit; will verify visually
- [ ] **Step 2: Create NumberBag component** with animation using Framer Motion: while `isShaking` true, rotate and scale; while `drawing` emits number ball with motion
- [ ] **Step 3: Create RiceGrain component** — when placed, animate drop (y: -100 to 0 with bounce) using `motion.div`
- [ ] **Step 4: Create retroTheme.js** with color palette: nâu gỗ, vàng ố, đỏ đất, xanh lá cũ; fonts: handwriting retro; textures optional (use CSS patterns)
- [ ] **Step 5: Apply retro theme to components** (buttons, cards)
- [ ] **Step 6: Manual QA**: run app, verify animations smooth (≥30fps)
- [ ] **Step 7: Commit** "feat: animations and retro styling"

### Task 16: In-Game HUD & Controls

**Files:**
- Create: `client/src/components/Game/PlayersPanel.jsx`
- Create: `client/src/components/Game/KinhButton.jsx`
- Create: `client/src/components/Game/ChatPanel.jsx`
- Modify: `client/src/components/Game/GameBoard.jsx` to include these

- [ ] **Step 1: Write failing test** — `client/src/components/Game/KinhButton.test.jsx`: test disabled when not playing; click calls `callKinh`
- [ ] **Step 2: Implement PlayersPanel**:
  - Shows list: avatar, name, ready status, balance (pre-game), grains count
  - Updates via GameContext
- [ ] **Step 3: Implement KinhButton**:
  - Visible only during playing and after user has completed at least one row (check row completeness from grains)
  - Clicking emits `callKinh`; button disabled after click to prevent spam
  - Shows countdown timer if freeze window active? Could show "Verifying..." message
- [ ] **Step 4: Implement ChatPanel**:
  - Simple input + send button; messages list scrolling; emits `chat` event; receives `chat_message`
  - No persistence beyond current room
- [ ] **Step 5: Run tests** — pass
- [ ] **Step 6: Commit** "feat: in-game HUD, players panel, Kinh button, chat"

---

## Phase 4 (cont'd): Economy, Social & Polish — 2 weeks

### Task 17: Coin Economy & Daily Bonus

**Files:**
- Create: `server/routes/economy.js`
- Create: `server/services/coinService.js` (extend with dailyBonus)
- Create: `client/src/components/Profile/CoinWallet.jsx`
- Create: `client/src/components/Profile/DailyBonusButton.jsx`

- [ ] **Step 1: Write failing test** — `server/services/coinService.test.js`: test `claimDailyBonus(userId)` gives coins only if last claim >24h ago; updates `last_claimed_at` in users (add column); test failure if already claimed
- [ ] **Step 2: Add DB column** `last_daily_bonus_at TIMESTAMP` to users (migration `002_add_daily_bonus.sql`)
- [ ] **Step 3: Implement `claimDailyBonus` in coinService** with 24h check; inserts coin_transaction type=DAILY_BONUS
- [ ] **Step 4: Create route `POST /api/economy/daily-bonus`** protected by auth; calls service; returns new balance
- [ ] **Step 5: Frontend: DailyBonusButton** that calls endpoint, shows next available time; update AuthContext user balance after success
- [ ] **Step 6: Run tests** — pass
- [ ] **Step 7: Commit** "feat: daily coin bonus system"

### Task 18: Achievements System

**Files:**
- Create: `server/routes/achievements.js`
- Create: `server/services/achievementService.js`
- Create: `server/db/migrations/003_achievements.sql` (tables: achievements, user_achievements)
- Create: `client/src/components/Profile/AchievementsList.jsx`

- [ ] **Step 1: Write failing test** — define achievement logic: e.g., FIRST_WIN (first Kinh win), CONCURRENT_KINH_3 (call Kinh with >=2 others simultaneously). Test that when game_settled event emitted, service checks and grants achievements; test duplicate prevention
- [ ] **Step 2: Create DB tables**:
  - `achievements` (id, code unique, name, description, coin_reward)
  - `user_achievements` (user_id, achievement_id, earned_at, UNIQUE(user_id,achievement_id))
- Insert seed data for several achievements
- [ ] **Step 3: Implement achievementService**:
  - `checkAndGrantAchievements(userId, event, payload)` — switch on event (e.g., 'game_settled'); query user stats; if not earned, insert into user_achievements and add coin_reward via coinService
  - `getUserAchievements(userId)` for UI
- [ ] **Step 4: Wire achievement check** into `processKinhClaims` after settlement: emit event to achievementService for each winner (and possibly others)
- [ ] **Step 5: Route `GET /api/achievements`** returns list of all achievements with earned flag
- [ ] **Step 6: Frontend: AchievementsList** component displays badges, earned status, coin rewards
- [ ] **Step 7: Run tests** — pass
- [ ] **Step 8: Commit** "feat: achievements system with coin rewards"

### Task 19: Spin Wheel Mini-Game

**Files:**
- Create: `server/routes/spin-wheel.js`
- Create: `server/services/spinWheelService.js`
- Create: `client/src/components/Profile/SpinWheel.jsx`

- [ ] **Step 1: Write failing test** — test `spinWheel(userId)` returns random prize segment; test cooldown (24h); test probability distribution
- [ ] **Step 2: Add DB columns** to users: `last_spun_at TIMESTAMP`
- [ ] **Step 3: Define wheel segments** array: `[{label: '100 coins', reward: 100, weight: 50}, {label: '500 coins', reward: 500, weight: 10}, {label: 'Try again', reward: 0, weight: 40}]` etc.
- [ ] **Step 4: Implement spinWheelService**:
  - Weighted random selection based on segments
  - Check cooldown; if available, grant coins via coinService, set `last_spun_at`, return prize
- [ ] **Step 5: Route `POST /api/spin`** returns prize result and new balance
- [ ] **Step 6: Frontend: SpinWheel component** with animated wheel (Framer Motion spin animation), button to spin (disabled if on cooldown), display result
- [ ] **Step 7: Run tests** — pass
- [ ] **Step 8: Commit** "feat: daily spin wheel mini-game"

### Task 20: Chat System

**Files:**
- Modify backend: `server/socket/handlers/gameHandlers.js` to store chat in Redis list `room:{roomId}:chat` (max 100) and broadcast `chat_message`
- Modify frontend: `client/src/components/Game/ChatPanel.jsx` already created; ensure displays messages with sender name and timestamp

- [ ] **Step 1: Write failing test** — integration test: two sockets in same room; one sends chat; other receives event with correct sender and message
- [ ] **Step 2: Implement server** chat handler:
  - `onChat(socket, { message })`: validate non-empty, length < 200; record in Redis list (LTRIM to keep last 100); broadcast `chat_message` with userId, name (from room_players), message, timestamp
- [ ] **Step 3: Implement client** ChatPanel: maintain local messages array; on `chat_message` event, append; scroll to bottom
- [ ] **Step 4: (Optional) Profanity filter** — simple blacklist array; filter message before broadcast; if blocked, emit error to sender only
- [ ] **Step 5: Run tests** — pass
- [ ] **Step 6: Commit** "feat: in-room chat"

### Task 21: Profile & Stats

**Files:**
- Create: `server/routes/profile.js`
- Create: `client/src/components/Profile/ProfilePage.jsx`
- Modify: `client/src/App.jsx` add route for profile

- [ ] **Step 1: Write failing test** — `server/routes/profile.test.js`: test GET returns user stats: total_wins, total_losses, recent history (last 10 coin_transactions)
- [ ] **Step 2: Implement route**:
  - `GET /api/profile` → selects from users, left join coin_transactions, returns summary and recent history
- [ ] **Step 3: Frontend ProfilePage** displays: avatar (from user record if Zalo, else placeholder), name, coins, win/loss counts, recent transactions in table, achievements section (link to AchievementsList), daily bonus button, spin wheel section
- [ ] **Step 4: Navigation** to profile from lobby
- [ ] **Step 5: Run tests** — pass
- [ ] **Step 6: Commit** "feat: user profile and stats page"

---

## Phase 5: Testing, Docker & Deployment — 1 week

### Task 22: Jest Unit Tests (Comprehensive)

**Files:**
- Create: `server/jest.config.js`
- Create: `client/jest.config.js` (if using Jest for React)
- Fill: multiple unit tests for all services: auth, coinService, boardService, drawEngine, kinhService

- [ ] **Step 1: Write tests** for every service function (see earlier tasks). Aim 80%+ coverage.
- [ ] **Step 2: Configure Jest** for server (babel or ts if using TS; we're using plain JS so default)
- [ ] **Step 3: Add test script** to server/package.json: `"test": "jest"`
- [ ] **Step 4: Run coverage** and fix any gaps
- [ ] **Step 5: Commit** "test: comprehensive unit test suite"

### Task 23: Cypress E2E Multi-Player Tests

**Files:**
- Create: `client/cypress.config.js`
- Create: `client/cypress/e2e/create-room.cy.js`
- Create: `client/cypress/e2e/gameplay.cy.js`
- Create: `client/cypress/e2e/concurrent-kinh.cy.js`

- [ ] **Step 1: Write failing test** (setup): test that Cypress can visit app and create a room
- [ ] **Step 2: Implement `create-room.cy.js`**:
  - Visit app, login anonymous, create room, verify room created, join second browser instance (using `cy.origin` or two windows simulation)
- [ ] **Step 3: Implement `gameplay.cy.js`**:
  - 2 players join room, ready, game starts; simulate placing grains; call Kinh; verify settlement and balances
- [ ] **Step 4: Implement `concurrent-kinh.cy.js`**:
  - 4 players; simulate near-simultaneous Kinh calls (some valid, some invalid); verify final balances match expected penalty distribution
- [ ] **Step 5: Add Cypress to client package.json**; script `"cypress:open"` and `"cypress:run"`
- [ ] **Step 6: Run E2E suite** to ensure passes
- [ ] **Step 7: Commit** "test: Cypress E2E multi-player scenarios"

### Task 24: Docker & Docker Compose for Production-Like Local

**Files:**
- Create: `Dockerfile` (for backend)
- Create: `client/Dockerfile` (for frontend static build)
- Modify: `docker-compose.yml` to include services: `frontend`, `backend`, `postgres`, `redis`
- Create: `.dockerignore`

- [ ] **Step 1: Write failing test** — none
- [ ] **Step 2: Write backend Dockerfile**:
  - Node 20 alpine
  - Copy package.json, install, copy server/, expose 3001, CMD `node server/index.js`
- [ ] **Step 3: Write frontend Dockerfile**:
  - Node 20 alpine; copy client package.json; install; copy client/; `npm run build`; output static files; serve with nginx: `nginx:alpine` and copy build to `/usr/share/nginx/html`
- [ ] **Step 4: Update docker-compose** to build and link services; set env vars; frontend depends on backend; network them
- [ ] **Step 5: Test local docker compose up** — app accessible at http://localhost (frontend) and backend ws at ws://localhost:3001
- [ ] **Step 6: Commit** "feat: Docker and docker-compose for full stack"

### Task 25: GitHub Actions CI

**Files:**
- Create: `.github/workflows/ci.yml`

- [ ] **Step 1: Write failing test** — none
- [ ] **Step 2: Create CI workflow**:
  - Triggers on push to main, PRs
  - Jobs:
    - `backend-tests`: setup Node, run `npm ci`, `npm test` in server/, also lint
    - `frontend-tests`: setup Node, run `npm ci`, `npm test` in client/ (if unit tests exist), also `npm run build` to ensure build succeeds
    - `e2e-tests`: uses Cypress Docker image; run `npm run cy:run` in client/; needs backend service running (docker compose up -d inside workflow? Use Cypress included services? Simpler: spin up backend via docker compose in before_script)
  - Upload artifacts (screenshots, videos) on failure
- [ ] **Step 3: Commit** "ci: GitHub Actions pipeline"

### Task 26: Free Tier Deployment Configuration

**Files:**
- Create: `client/vercel.json` (or rely on defaults)
- Create: `railway.json` for backend (or use Dockerfile)
- Update: `client/.env.production` with VITE_API_URL and VITE_WS_URL pointing to Railway backend URL (which will be set as env at deploy time)
- Create: `server/.env.production.example` with required vars (Railway provides DATABASE_URL etc.)

- [ ] **Step 1: Write failing test** — none
- [ ] **Step 2: Create Vercel config** (optional) for SPA routing redirects
- [ ] **Step 3: Prepare Railway deployment**: ensure Dockerfile present; add `railway.json` if needed (just specify Docker build)
- [ ] **Step 4: Document environment variables** required for production in README
- [ ] **Step 5: Commit** "deploy: free tier configs for Vercel + Railway"

### Task 27: Zalo Mini App Build Script

**Files:**
- Create: `client/package.json` scripts: `"build:zalo": "vite build --config vite.zalo.config.js"`
- Create: `client/vite.zalo.config.js` with appropriate base and output dir `dist/zalo`
- Create: `client/zalo.config.json` (Zalo Mini App manifest) (placeholder)
- Create: `client/src/platforms/zalo/adapter.js` to wrap Zalo SDK calls

- [ ] **Step 1: Write failing test** — none
- [ ] **Step 2: Create Zalo-specific Vite config** that sets base to `./`, outputs to `dist/zalo`, builds as library? (Zalo Mini App expects a single JS file and assets). We'll produce static assets.
- [ ] **Step 3: Create zalo.config.json** with appID, name, version, orientation, etc. (placeholders)
- [ ] **Step 4: Create Zalo adapter** that provides methods: `login()`, `share()`, `getUserInfo()`. Use real SDK when in Zalo environment; fallback to mock in web.
- [ ] **Step 5: Update Auth flow** to use ZaloLoginButton that calls adapter.login; on success, hit backend Zalo OAuth flow
- [ ] **Step 6: Build test**: run `npm run build:zalo` and verify output in `dist/zalo/`
- [ ] **Step 7: Commit** "feat: Zalo Mini App build configuration"

---

## Post-Implementation: Local Development & QA

- Ensure `docker-compose up` brings up everything
- Backend runs on :3001, frontend on :5173 (Vite default)
- Provide instructions in README for running locally and for deployment

---

## Notes for Subagent Workers

- **TDD:** ALWAYS write test FIRST, then code to make it pass. No exceptions.
- **Commits:** Small, logical commits after each step with clear messages.
- **Self-review:** After completing your assigned tasks, run the tests, lint, and check that your code follows the architecture in the spec.
- **Cross-review:** After your task is complete and self-reviewed, you will be asked to review another worker's code. Use the 3-tier review criteria: Plan Alignment, Code Quality, Architecture, Documentation, Issues.
- **Blockers:** If you encounter a dependency on another task that is not yet done, ask the orchestrator to reorder tasks or create a minimal stub.

---

**Plan complete and saved to `docs/superpowers/plans/2026-03-31-lotto-game-full-stack.md`.**

**Execution approach:** Subagent-Driven (you will dispatch fresh subagents per task or small task group). I will now begin spawning subagents for Phase 1 tasks sequentially, ensuring each task is fully implemented, reviewed, and committed before moving to the next.

Let's start with **Task 1: Initialize Backend Project & Docker Compose**.