mirza-mohammad24/scribblitz

Purpose and Runtime Topology

Scribblitz is a multiplayer drawing-and-guessing game. It is a pnpm/Turborepo monorepo with three Node.js services: Next.js browser UI, Express/Socket.IO authoritative game server, and BullMQ AI worker. Shared contracts prevent client/server event drift.

• apps/web/src/app/page.tsx

• apps/game-server/src/server.ts

• apps/worker/src/index.ts

Client Application and UI Control

The Next.js app renders the home, lobby, and active-game experiences. ArenaOrchestrator is the top-level game UI router: it consumes socket-driven state from Zustand and selects lobby versus arena views; arena components isolate canvas, chat, HUD, leaderboard, overlays, emotes, and voice controls.

• apps/web/src/components/Arena/ArenaOrchestrator.tsx

• apps/web/src/store/gameStore.ts

• apps/web/src/hooks/useGameSocket.ts

Authoritative Room and Game Lifecycle

The game server owns ephemeral room membership, host assignment, player sessions, reconnect grace periods, and all gameplay transitions. RoomManager manages in-memory rooms; GameFSM permits the lobby → word selection → drawing → round end/game end lifecycle. Socket handlers enforce role/state guards before invoking this domain layer.

• apps/game-server/src/rooms/RoomManager.ts

• apps/game-server/src/rooms/Room.ts

• apps/game-server/src/fsm/GameFSM.ts

Socket Boundary and Shared Contracts

Socket.IO is the primary control and realtime data plane between browser and game server. Handler groups separate lobby/configuration, gameplay, messages/guessing, canvas, voice, and emotes. Incoming payloads are runtime-validated with Zod; types, event names, game states, and constants are workspace-owned.

• apps/game-server/src/socket/handlers/gameHandlers.ts

• packages/types/src/events.ts

• packages/validation/src/game.ts

Drawing Synchronization and Recovery

The drawer locally buffers pointer operations and sends batched canvas events; the server immediately relays them to peers and persists/retrieves history through Redis. Canvas logic stays client-local, while server handlers enforce drawer and round permissions. Redis Streams support reconnect/late-join replay but do not store authoritative room state.

• apps/web/src/hooks/useCanvasDrawing.ts

• apps/game-server/src/socket/handlers/canvasHandlers.ts

• apps/game-server/src/lib/redis.ts

External Services and Background Work

Redis backs both canvas streams and BullMQ. Hosts request themed words through the game server; it enqueues work and the worker calls Google Gemini, then validates/filter results before completion is reflected in room configuration. Voice is separate: the game server mints scoped LiveKit tokens, while browsers carry audio directly over WebRTC to LiveKit.

• apps/game-server/src/services/aiQueue.ts

• apps/worker/src/index.ts

• apps/game-server/src/services/voiceService.ts

Persistence and Deployment Boundaries

PostgreSQL/Prisma provides schema and migrations for persistent entities such as users and game results, though active games remain process-local. Docker Compose provisions local dependencies and production services; each runtime has a Dockerfile. The architecture is currently single-instance because rooms are not distributed via a Socket.IO Redis adapter.

• prisma/schema.prisma

• docker-compose.yml

• docker-compose.prod.yml