Engineering case study
Chkobba
A Tunisian classic. A shared, real-time table.
Online Chkobba for private 1v1 and 2v2 rooms, ranked matchmaking, and personality-driven AI opponents, built around server-authoritative game state.
The problem
Moving a card game online means more than rendering cards. Players need one consistent match state, enforceable rules, synchronized turns, and a way to reconnect without letting browsers decide which moves are legal.
Project context
Real-time multiplayer / Full-stack engineering
Implementation scope
- A Next.js game interface with Zustand state and Socket.IO player intent.
- A pure TypeScript engine for rules, scoring, AI, and tests, shared with the realtime server.
- Guest play plus Supabase-backed accounts, match history, friends, ranked ratings, and progression.
Product walkthrough
Recorded product demo. Features shown reflect the version in this recording.
System architecture
- 01Player intent
- 02Server validation
- 03Game engine
- 04Approved state
- 05Match history
Player interface
Next.js / React / Zustand
Renders a sanitized game view and sends intent without deciding move legality.
Authoritative server
Node.js / Socket.IO
Owns rooms, turns, timers, validation, bots, reconnects, and match persistence.
Rules & contracts
TypeScript / pnpm workspaces
Pure game engine and shared event/DTO types, independent of the browser and database.
Player persistence
Supabase / PostgreSQL
Authentication, history, friends, ranked ratings, and progression; optional for guest play.
Engineering decisions
01One authority for every move.
The realtime server owns the game state. Browsers submit intent and receive sanitized, server-approved views rather than acting as the rules authority.
02Rules without framework dependencies.
The game engine contains no React, Socket.IO, database, or browser code. Rules, scoring, and AI can be tested independently of transport and UI.
03Guest play stays independent of accounts.
Supabase is optional for guest play and required for account-based history, friends, ranked ratings, and progression. Core gameplay and account services have distinct boundaries.
04Deploy the web and realtime server separately.
The documented deployment uses Vercel for the Next.js frontend and Render for the realtime server, with Supabase migrations deployed before server changes that depend on them.
Engineering takeaways
- Realtime consistency starts with clear ownership of state.
- A pure rules engine separates correctness from rendering and networking.
- Shared contracts keep player intent and server-approved views aligned.
Next steps
The README identifies engine tests as the source of truth for captures, scoring, dealer rotation, and 1v1/2v2 rules. Further case-study updates can document measured reconnect behavior and player feedback once those results are available.