# Chess App

A production-grade, real-time multiplayer chess platform

Play chess against anyone in the world — instantly, in real-time.

[Features](#-features) · [Architecture](#-architecture) · [Tech Stack](#-tech-stack) · [Getting Started](#-getting-started) · [Roadmap](#-roadmap)

---

Overview :

Chess App is a full-stack multiplayer chess platform built on a **monorepo architecture**. It leverages WebSockets for sub-100ms move synchronization, `chess.js` for bulletproof move validation, and PostgreSQL for persistent game state — all orchestrated with Turborepo across three independent services.

Recently Features added

• Reconnect to existing games
• Basic Matchmaking queue
• Game state saving to database

Architecture

Current System

The current architecture uses a **single WebSocket server** that handles all real-time game logic. The HTTP backend manages authentication and user data independently, while both services share types and database access via monorepo packages.
## Tech Stack

Layer	Technology
Frontend	React 19, TypeScript, Vite, Tailwind CSS, Lucide React
HTTP API	Express.js, TypeScript, JWT Auth
Game Server	Node.js WebSockets (ws), chess.js
Database	PostgreSQL, Prisma ORM
Monorepo	Turborepo, pnpm workspaces

## Project Structure

chess-app/
├── apps/
│   ├── frontend/          # React 19 + Vite client
│   ├── backend/           # Express REST API (auth, users)
│   └── ws/                # WebSocket game server
│
├── packages/
│   ├── db/                # Prisma schema + generated client
│   ├── backend-common/    # Shared JWT utils, middleware
│   ├── ui/                # Shared React component library
│   ├── eslint-config/     # Unified lint rules
│   └── typescript-config/ # Base tsconfig
│
├── turbo.json
└── pnpm-workspace.yaml

Prerequisites

• Node.js >= 18
• pnpm >= 9 — npm install -g pnpm
• PostgreSQL >= 14

1 · Clone & Install

git clone <your-repo-url>
cd chess-app
pnpm install

2 · Configure Environment

Create the database env file:

# packages/db/.env
DATABASE_URL="postgresql://user:password@localhost:5432/chessapp"

Create env files for each app:

# apps/backend/.env
PORT=4000
JWT_SECRET=your_super_secret_key
DATABASE_URL="postgresql://user:password@localhost:5432/chessapp"
 
# apps/ws/.env
PORT=3000
JWT_SECRET=your_super_secret_key
DATABASE_URL="postgresql://user:password@localhost:5432/chessapp"

3 · Set Up Database

cd packages/db
npx prisma migrate dev --name init
npx prisma generate
cd ../..

4 · Run All Services

pnpm dev

Turborepo starts all three services in parallel:

Service	URL
Frontend	http://localhost:5173
HTTP API	http://localhost:4000
WebSocket	ws://localhost:3000

## Features

Live

• ♟ Real-time gameplay — moves sync in under 100ms via WebSockets
• ✅ Move validation — server-side enforcement via chess.js (no cheating)
• 🔐 Authentication — JWT-based sign up / sign in
• 💾 Game persistence — full game state saved to PostgreSQL
• 📱 Responsive UI — works on mobile and desktop

Future (Planned) (V2)

• In-game chat
• Video call integration
• Engine analysis & accuracy detection
• ELO rating & leaderboard
• Spectator mode
• Horizontal WebSocket scaling (Redis pub/sub)

## How a Game Works

1. Player A opens the app → connects via WebSocket with JWT
2. Player A clicks "New Game" → server creates a game room
3. Player B joins the room → server pairs them, assigns colors
4. Player A moves e2→e4:
     Client → WS Server → chess.js validates → broadcasts to Player B
                                              → persists to PostgreSQL
5. Player B sees the move instantly (<100ms)
6. Game over → result saved, players disconnected

## Contributing

# Run lint across all packages
pnpm lint
 
# Type check
pnpm typecheck
 
# Build all packages
pnpm build

All PRs should target the main branch. Please open an issue before making large changes.

---

License

ISC License — see package.json for details.

---