Chess Clone

A real-time multiplayer chess application built with React, Node.js, Socket.IO, and PostgreSQL. Features include matchmaking, live gameplay, game history, and a responsive chess board interface.

Features

<� Core Gameplay

• Real-time Chess: Play chess with other players in real-time using Socket.IO
• Interactive Chess Board: Drag-and-drop interface powered by react-chessboard
• Move Validation: Server-side move validation using chess.js
• Game States: Support for checkmate, stalemate, draws, and resignations

=� Matchmaking System

• Queue-based Matchmaking: Join a queue to find opponents with similar ratings
• Real-time Queue Updates: See live updates of players in queue and wait times
• Automatic Pairing: Random color assignment when matches are found

=� Game Management

• Game History: View your recent games with results and statistics
• Resume Games: Continue active games from where you left off
• Game Timeout: Automatic draw after 10 minutes of inactivity
• Spectator Mode: View completed games

=d User System

• User Registration/Login: Secure authentication with JWT tokens
• Player Ratings: Elo-based rating system (starting at 1200)
• User Profiles: Track games played and current rating

Tech Stack

Frontend

• React 18 with TypeScript
• React Router for navigation
• Socket.IO Client for real-time communication
• react-chessboard for the chess interface
• chess.js for game logic
• Axios for API requests
• Tailwind CSS for styling

Backend

• Node.js with Express and TypeScript
• Socket.IO for WebSocket connections
• PostgreSQL with connection pooling
• JWT for authentication
• bcryptjs for password hashing
• chess.js for server-side game validation

Database

• PostgreSQL (compatible with Supabase)
• UUID primary keys for better scalability
• Row Level Security policies

Getting Started

Prerequisites

• Node.js 18+ and npm
• PostgreSQL 14+ (or Supabase account)
• Git

Installation

1. Clone the repository

   git clone https://github.com/yourusername/chess-clone.git
   cd chess-clone

2. Install backend dependencies

   cd backend
   npm install

3. Install frontend dependencies

   cd ../frontend
   npm install

4. Database Setup

   Supabase

   • Create a new Supabase project
   • Go to SQL Editor and run the contents of backend/supabase-schema.sql
   • Get your database URL from Settings > Database

5. Environment Configuration

   Backend (.env)

   # Supabase, transaction pooler uri
   # DATABASE_URL=postgresql://postgres.[project id]:[YOUR-PASSWORD]@aws-1-us-east-1.pooler.supabase.com:6543/postgres
   
   # Security
   JWT_SECRET=your-super-secret-jwt-key-here
   
   # CORS
   FRONTEND_URL=http://localhost:3000
   
   # Server
   PORT=5000

   Frontend (.env)

   REACT_APP_API_URL=http://localhost:5000/api
   REACT_APP_SOCKET_URL=http://localhost:5000

Running the Application

1. Start the backend server

   cd backend
   npm run dev

   Server will start on http://localhost:5000

2. Start the frontend development server

   cd frontend
   npm start

   Application will open at http://localhost:3000

3. Create user accounts and start playing!

Project structure

chess-clone/
├── backend/
│   ├── src/
│   │   ├── config/
│   │   │   ├── database.ts          # Database connection
│   │   │   └── index.ts             # App configuration
│   │   ├── middleware/
│   │   │   └── auth.ts              # JWT authentication
│   │   ├── models/
│   │   │   ├── Game.ts              # Game database model
│   │   │   └── User.ts              # User database model
│   │   ├── routes/
│   │   │   ├── auth.ts              # Authentication routes
│   │   │   └── games.ts             # Game routes
│   │   ├── services/
│   │   │   ├── GameService.ts        # Game logic & caching
│   │   │   ├── MatchmakingService.ts # Queue management
│   │   │   ├── SocketService.ts      # Socket.IO handling
│   │   │   └── GameTimeoutService.ts # Game timeouts
│   │   ├── app.ts                   # Express app setup
│   │   └── server.ts                # Server entry point
│   ├── migrations/                  # Database migrations
│   │   └── supabase-schema.sql      # Complete DB schema
│   └── package.json
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── ChessBoard.tsx       # Main game component
│   │   │   ├── Lobby.tsx            # Matchmaking lobby
│   │   │   ├── LoginForm.tsx        # User login
│   │   │   └── RegistrationForm.tsx # User registration
│   │   ├── contexts/
│   │   │   ├── AuthContext.tsx      # Authentication state
│   │   │   └── SocketContext.tsx    # Socket connection
│   │   ├── config.ts                # API configuration
│   │   └── App.tsx                  # Main app component
│   └── package.json
│
└── README.md

API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login

Games

• GET /api/games/my-games - Get user's game history
• GET /api/games/:gameId - Get specific game details
• POST /api/games/create - Create a new game (deprecated, use matchmaking)

Socket Events

Client � Server

• join-matchmaking - Join the matchmaking queue
• leave-matchmaking - Leave the matchmaking queue
• join-game - Join a specific game room
• make-move - Make a chess move
• offer-draw - Offer a draw to opponent
• accept-draw / decline-draw - Respond to draw offer
• resign - Resign from the game

Server � Client

• match-found - Match found with game details
• game-joined - Successfully joined game
• move-made - Opponent made a move
• game-over - Game ended with result
• draw-offered / draw-accepted / draw-declined - Draw offer updates
• opponent-disconnected - Opponent left the game

Development

Building for Production

Backend:

cd backend
npm run build
npm start

Frontend:

cd frontend
npm run build
# Serve the build folder with a web server

Database Migrations

The project uses SQL files for database schema. To make changes:

1. Update backend/supabase-schema.sql
2. Create migration files in backend/migrations/
3. Apply changes to your database

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Performance Optimization

• Game Caching: Active games are cached in memory for faster access
• Connection Pooling: Database connections are pooled for efficiency
• Queue Optimization: Matchmaking uses in-memory data structures

Acknowledgments

• chess.js for chess game logic
• react-chessboard for the chess board component
• Socket.IO for real-time communication

---

Happy Chess Playing! _�