ChessGo

ChessGo is a real-time online chess game where players can play against each other or against a computer opponent (Stockfish). It is built as a monorepo containing the frontend, game server, and database packages.

About

Players can sign in or play as guests, get matched for timed games, and play against Stockfish. Chess rules are validated on the server to prevent illegal moves. Profiles include wins, losses, bio, avatar, and match history.

Features

1. User registration, login, and guest play
2. Real-time matchmaking
3. Server-side chess rule validation
4. Timed games with increment support
5. Draw offers, resignations, rematches, and reconnection
6. Computer games using Stockfish
7. Public player profiles and username search
8. Profile editing
9. Custom chess pieces and pawn-promotion selection

Tech Stack

Part	Technology
Frontend	Next.js, React, TypeScript, Tailwind CSS
Chessboard	chess.js, react-chessboard
Backend	Node.js, Express, ws
Chess rules	chess.js
Computer opponent	Stockfish (UCI)
Authentication	JWT, bcrypt
Database	PostgreSQL
ORM	Prisma
Tooling	Turborepo, npm workspaces
Deployment	GitHub Actions

Project Structure

chessgo
├── apps
│   ├── web                 # Next.js frontend
│   └── websocket-server    # Real-time game server
├── packages
│   ├── db                  # Database
│   ├── ui                  # Shared UI
│   ├── eslint-config       # ESLint configuration
│   └── typescript-config   # TypeScript configuration
├── PRODUCT.md
├── explain.md
└── turbo.json

How It Works

   Your Browser                          Game Server
 ┌───────────────┐     web page          ┌─────────────────────┐
 │               │ ───────────────────▶  │  Express (login,    │
 │   Next.js     │  login, profile info  │  profile, history)  │
 │   website     │ ◀───────────────────  │                      │
 │               │                       │                      │
 │               │     live game data    │  GameManager         │
 │               │ ═══════════════════▶  │  (matches players)   │
 │               │  moves, draws, chat   │        │              │
 │               │ ◀═══════════════════  │        ▼              │
 └───────────────┘                       │  Game / BotGame       │
                                          │  (chess rules, clock) │
                                          │        │              │
                                          │        ▼              │
                                          │    Stockfish engine   │
                                          │    (for bot games)    │
                                          └──────────┬────────────┘
                                                      │
                                                      ▼
                                          ┌─────────────────────┐
                                          │   PostgreSQL        │
                                          │   (saved through    │
                                          │    Prisma)          │
                                          └─────────────────────┘

The Next.js frontend communicates with the backend through normal HTTP APIs for authentication and profiles and WebSockets for live games. The server manages matchmaking, validates moves, handles clocks and game results, and saves completed games to PostgreSQL through Prisma. Stockfish is used for computer games.

Database

User

Field	What it stores
id	a number that identifies the player
username	the player's name, must be unique
password	a protected password (empty for guest accounts)
bio	a short description the player writes about themselves
avatarUrl	a link to the player's profile picture
wins	how many games the player has won
losses	how many games the player has lost
gamesPlayed	how many games the player has played in total
createdAt	the date the account was created

Game

Field	What it stores
id	a code that identifies the game
whitePlayerId	the id of the player using white pieces
blackPlayerId	the id of the player using black pieces
winnerId	the id of the winner, empty if it was a draw
status	whether the game is still playing, finished, or abandoned
moves	how many moves were played
startedAt	when the game began
endedAt	when the game ended

Getting Started

Requirements:

• Node.js 18+
• PostgreSQL

git clone https://github.com/devsterxyz/chessgo.git
cd chessgo
npm install

Set the required environment variables:

DATABASE_URL=postgresql://user:password@host:5432/database
JWT_SECRET_KEY=your_secret_key
REFRESH_TOKEN_SECRET_KEY=your_other_secret_key
PORT=3002
WS_PORT=8080

Set up the database:

npm run db:generate
npm run db:migrate

Start the application:

npm run dev

The frontend runs on http://localhost:3000, the API server on http://localhost:3002, and the WebSocket server on port 8080.

API Overview

HTTP API

Method	Path	Purpose
POST	/user/register	Create an account
POST	/user/signIn	Log in
POST	/user/logout	Log out
POST	/user/guest	Create a guest account
GET	/user/getProfile	Get own profile
PUT	/user/updateProfile	Update profile
GET	/game/history/:username	Get match history
GET	/profile/search	Search players
GET	/profile/:username	View public profile

WebSocket

The WebSocket server handles matchmaking, bot games, moves, resignations, draws, reconnection, and rematches.

Game Flow

1. A player starts matchmaking or a computer game.
2. A game is created once an opponent is available.
3. Moves are sent to and validated by the server.
4. The server manages the board, clocks, and game-ending conditions.
5. Results are saved to the database.
6. Players can rematch after the game.

Deployment

GitHub Actions automatically deploys new changes from the main branch by updating, building, and restarting the application.

License

This project is licensed under the MIT License.

Copyright (c) 2026 Dev Sharma