REAL-TIME / BACKEND
Real-Time Chess App
A multiplayer chess backend with dedicated WebSocket infrastructure, durable game history, and live state management.
Overview
A multiplayer chess backend with a dedicated WebSocket server for real-time game state, Redis for live game state and session management, PostgreSQL for durable game history, JWT authentication with Google OAuth, and full CI/CD with Docker and automated testing.
The Problem
Real-time multiplayer games require sub-second state synchronization, graceful reconnection handling, durable game history, and clean separation between ephemeral live state and persistent records.
Architecture
Key Decisions
Redis/PostgreSQL separation
Redis holds live game state for fast reads/writes during active games. PostgreSQL persists completed games and player records for durability.
WebSocket-first architecture
Dedicated WebSocket server handles all game events — moves, clock updates, resignations — with no polling overhead.
Reconnection handling
Players can disconnect and reconnect mid-game; the server restores game state from Redis and resumes the session seamlessly.
JWT + Google OAuth
JWT for session management with Google OAuth for frictionless authentication.
Failure Modes
Player disconnect mid-game
Game state persists in Redis; player reconnects and resumes from last known state.
Server restart during active game
Redis persistence ensures live games survive server restarts; PostgreSQL has completed game history.
Concurrent move attempts
Server-side move validation prevents illegal or out-of-turn moves.
Authentication expiry
JWT refresh flow handles token expiry without disrupting active games.
Implementation
- WebSocket server for real-time game events
- Redis for live game state and session management
- PostgreSQL with Prisma ORM for durable game history
- Reconnection handling with state restoration
- JWT authentication with Google OAuth integration
- Docker containerization for consistent deployment
- GitHub Actions CI/CD pipeline
- Vitest automated test suite
Lessons
- —Separating live state (Redis) from durable state (PostgreSQL) is the right pattern for real-time games.
- —Reconnection handling is where most multiplayer backends fail — design for it from the start.
- —Automated testing with Vitest catches game logic bugs that manual testing misses.