Connect Four Realtime - Distributed Gaming System

A real-time multiplayer Connect Four game implemented as a microservices architecture, demonstrating scalable distributed systems principles with seamless WebSocket communication and automated service orchestration.

Note: This project showcases a complete migration from monolithic architecture to microservices, maintaining real-time gaming capabilities while achieving proper service separation and scalability.

What it does

• Distributed Backend: 4 independent microservices (User, Room, Game, Gateway) communicating via HTTP REST APIs
• Real-time Gaming: WebSocket-based multiplayer Connect Four with instant move synchronization
• Session Management: Token-based authentication with automatic session cleanup
• Game Orchestration: Automated room lifecycle, player matching, and game state management
• Cross-platform Clients: Web interface and mobile app with unified real-time experience

Why it matters

• Scalability Demonstration: Shows how to scale gaming services independently based on load
• Architecture Best Practices: Clean separation of concerns with proper service boundaries
• Real-time Challenges: Solves distributed state synchronization and WebSocket orchestration
• Fault Isolation: Service failures don't cascade, maintaining system reliability
• Modern Development: TypeScript throughout with shared packages and monorepo structure

Flow (end to end)

1. Service Discovery → Client navigates to room URL and establishes WebSocket connection
2. Authentication → Gateway proxies session validation to User Service via HTTP
3. Room Management → Room Service handles player joining and game state coordination
4. Game Logic → Move validation and win detection through Game Service API calls
5. Real-time Sync → WebSocket events broadcast state changes to all connected clients
6. Cleanup → Automatic room destruction and session cleanup when players leave

Architecture & Technical Implementation

Service Architecture

Client (WebSocket) ↔ Gateway Service ↔ [User/Room/Game Services]
                      ↓                        ↓
               Socket.IO Events        HTTP REST APIs

• Gateway Service (Port 3001): WebSocket server and API gateway routing requests
• User Service (Port 3002): Session token management and authentication
• Room Service (Port 3003): Game room orchestration and player coordination
• Game Service (Port 3004): Pure game logic, move validation, and win detection

Key Technical Challenges Solved

• State Synchronization: Maintaining consistent game state across distributed services
• WebSocket Orchestration: Coordinating real-time events through multiple service layers
• Service Communication: Reliable HTTP APIs between microservices with retry logic
• Shared Code Management: Extracted common utilities (CORS, HTTP helpers) to shared packages

Core Communication Patterns

// Service-to-Service HTTP Communication
const moveResponse = await fetchWithRetry(`${GAME_SERVICE_URL}/move`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ board, column, player })
});

// WebSocket Real-time Events
socket.on('make_move', async ({ column }) => {
  // Validate move through Game Service
  // Broadcast result to all room players
  io.to(roomCode).emit('state', updatedState);
});

Shared Infrastructure

• @packages/helpers: CORS middleware, HTTP retry logic, shared utilities
• @packages/types: TypeScript interfaces for APIs and WebSocket events
• Monorepo Structure: pnpm + Turborepo for workspace management
• Development Orchestration: Parallel service startup and hot reloading