EeChess

A modern, real-time online chess platform built with React, TypeScript, and WebSockets.

🎯 Overview

EeChess is a next-generation online chess application that enables players to compete in real-time matches through a beautiful, responsive web interface. Built with modern web technologies, it provides a seamless gaming experience with instant move synchronization.

✨ Features

• Real-time Gameplay: Instant move synchronization using WebSocket connections
• Reconnection Logic: Players can reconnect to an ongoing game if their connection drops
• Modern UI: Beautiful, responsive interface built with React and Tailwind CSS
• Type Safety: Full TypeScript implementation for better development experience
• Chess Engine: Powered by chess.js for accurate game logic and move validation
• Cross-platform: Works on desktop and mobile devices
• Spectator Mode: Allow users to watch ongoing games

🚀 Tech Stack

Frontend

• React - Modern UI framework
• TypeScript - Type-safe development
• Zustand - State management
• Tailwind CSS - Utility-first CSS framework
• React Chessboard - Professional chess board component
• Vite - Fast build tool and dev server
• Radix UI - Accessible UI components

Backend

• Node.js - JavaScript runtime
• WebSocket (ws) - Real-time communication
• chess.js - Chess game logic and validation
• Zod - Runtime type validation

Architecture

• Monorepo - PNPM workspace for shared code
• Shared Package - Common types and constants

📦 Project Structure

eechess/
├── apps/
│   ├── backend/          # WebSocket server and game logic
│   └── frontend/         # React application
├── packages/
│   └── shared/           # Shared types and constants
└── pnpm-workspace.yaml   # Workspace configuration

🛠️ Getting Started

Prerequisites

• Node.js (v18 or higher)
• PNPM (v8 or higher)

Installation

1. Clone the repository

   git clone <repository-url>
   cd eechess

2. Install dependencies

   pnpm install

3. Start the development servers

   In separate terminals:

   # Build the shared package first (required for backend)
   cd packages/shared
   pnpm build
   
   # Build and start the backend server
   cd ../../apps/backend
   pnpm build
   pnpm start

   # Start the frontend development server
   cd apps/frontend
   pnpm dev

4. Open your browser

   • Frontend: http://localhost:5173
   • Backend WebSocket: ws://localhost:8080

🎮 How to Play

1. Navigate to the application in your browser
2. Click "Play Online" to start a new game
3. Wait for an opponent to join
4. Make moves by dragging pieces on the chessboard
5. The game automatically validates moves and enforces chess rules

🔧 Development

Available Scripts

Backend:

• pnpm build - Build TypeScript to JavaScript
• pnpm start - Start the production server

Frontend:

• pnpm dev - Start development server
• pnpm build - Build for production
• pnpm lint - Run ESLint
• pnpm preview - Preview production build

WebSocket API

The application uses WebSocket messages for real-time communication:

Join Game: Used by a player to join a new or existing game. If gameId is provided, they will join as a spectator.

{
  "type": "joinGame",
  "payload": {
    "gameId": "some-game-id" 
  }
}

Reconnect to Game: Used by a player to reconnect to a game they were previously in.

{
  "type": "reconnect"
}

Initialize Game: Sent to a player when they start a new game, assigning them a color.

{
  "type": "initGame",
  "payload": {
    "color": "white",
    "gameId": "some-game-id"
  }
}

Make a Move:

{
  "type": "move",
  "payload": {
    "move": {
      "from": "e2",
      "to": "e4"
    }
  }
}

Game Over:

{
  "type": "gameOver",
  "payload": {
    "winner": "white"
  }
}

Game State: Sent to spectators to provide the current state of the game.

{
  "type": "gameState",
  "payload": {
    "moves": [],
    "turn": "w",
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
    "gameId": "some-game-id"
  }
}

🚧 Roadmap

• Chess Clock - Add time controls for games
• Spectators - Allow users to watch ongoing games
• State Management - Implement proper game state management
• Authentication - User accounts and persistent sessions
• Reconnection - Handle connection drops gracefully
• Game History - Save and replay completed games
• Tournaments - Organize competitive events

🙏 Acknowledgments

• chess.js - Chess game logic
• react-chessboard - Chess board component
• Tailwind CSS - CSS framework