Chess Master

Browser chess is either a heavy desktop install (lichess.org is great but not yours to extend) or a toy demo — illegal moves, no castling animation, clocks that freeze during AI thinking, and no way to challenge a friend without both players on the same keyboard. Competitive players want Stockfish-level analysis; casual players want a polished UI with hints and themes; friends want a private room code and real-time sync.

Most student chess projects stop at a draggable board with hardcoded rules. They skip en passant, threefold repetition, rated ELO persistence, OAuth login, WebSocket multiplayer with draw offers, post-game move review with quality labels, and a split frontend/server deploy that mirrors how real products ship. Chess Master targets that gap: a production-grade, zero-install chess app in the browser.

Solo Full-Stack Engineer & Product Owner — I designed and built Chess Master end-to-end.

**Frontend (frontend/):** Next.js 15 App Router single-page app, React 19, TypeScript, Tailwind CSS 4, Framer Motion. Landing page with hero board, auth screen (username/password + Google OAuth), game setup (mode, color, difficulty, rated/casual, timer), online lobby (create/join 6-char room codes), full game board with drag-and-drop, live eval bar (Stockfish WASM), Chess.com-style clock rail, move list with Lichess piece SVGs, settings panel (themes, sounds, hints, threats), game over + game review modals, stats/history screen with cloud replay.

**Chess engine (frontend/src/lib/chess/):** Custom Game class — full rule set (castling, en passant, promotion, checkmate, stalemate, draws), Minimax alpha-beta AI with piece-square tables and opening book, Stockfish 18 WASM in Web Worker for hard mode + live centipawn eval, FEN/PGN export, replay state machine, decoupled gameClock with wall-clock extrapolation during AI search.

**Backend (server/):** Express REST API, WebSocket server (ws), PostgreSQL 16 + Drizzle ORM, JWT auth (jose + bcrypt), Google OAuth 2.0 with CSRF state cookie, game save + ELO stats repository, room manager for online play (create/join/move/resign/draw), shared Game class imported from frontend for server-side move validation.

**Ops:** Split deploy — Vercel (frontend) + Render (API + WS), Neon PostgreSQL, SQL migrations, dev:all script for local full-stack.

**Chess Master** is a **two-package monorepo** — independently deployable frontend/ and server/.

1$   Next.js 15 (Vercel)
2$        │  REST                    │  WebSocket
3$        ▼                          ▼
4$   Express backend (Render) ── online rooms · matchmaking
5$        │                          │
6$        │                          └──▶ live moves · clocks
7$        │
8$        ├──▶ Stockfish 18   engine analysis · game review
9$        ├──▶ Minimax        local AI opponent
10$        │
11$        └──▶ PostgreSQL  (Drizzle ORM)
12$             users · games · ELO · PGN history

**Frontend stack:** Next.js 15.3, React 19, TypeScript 5.8, Tailwind CSS 4, Framer Motion, Lucide icons. Single entry page.tsx routes screens via state machine (LandingPage → StartScreen → ChessGame / OnlineLobby / StatsScreen / AuthScreen). Next.js rewrites proxy HTTP /api/* to API_URL; WebSocket connects directly to NEXT_PUBLIC_WS_URL.

**Server stack:** Express 4 on port 4000, WebSocket on 3001 (local dev), Drizzle ORM + pg pool, migrations in server/drizzle/ (users, oauth_accounts, games with jsonb history + PGN text).

**Game modes:** | Mode | Opponent | Auth | ELO | |------|----------|------|-----| | Local 2-player | Same device | No | No | | Minimax AI | Browser alpha-beta | No | Optional (rated) | | Stockfish AI | WASM engine | No | Optional (rated) | | Online | Remote friend | **Required** | No (v1) |

**Client chess pipeline:** User drags piece → Game validates move → animation (castleAnimation.ts for dual-piece castles) → update move list (SAN + piece icons) → if AI turn: async Minimax yields or Stockfish worker → clock ticks via useGameClock during search → on game end: modal + optional POST /api/games save.

**Online pipeline:** Host create_room → 6-char code → guest join_room via ?join=CODE deep link → JWT on ws://host?token= → moves broadcast at animation start for low latency → resign/draw offer/accept over WebSocket → game_over with correct winReason (checkmate vs resignation).

**ELO system:** Start 1200, K-factor 32, standard expected-score formula. Rated AI games only when "Track ELO" enabled. On save, server updates users.elo, wins, losses, draws in PostgreSQL; localStorage fallback when logged out.

**Auth flows:** Username/password → POST /api/auth/login → JWT in localStorage → Bearer on REST + ?token= on WS. Google OAuth → /api/auth/google → callback → redirect ?auth_token=JWT → frontend AuthContext hydrates user + cloud stats.

**UI highlights:** Marble/green/brown board themes, neo/classic piece sets, vertical Stockfish eval bar, opening name detection, threat highlighting, hint moves, confetti on wins, first-time tutorial overlay, resume incomplete local games from setup screen.

Chess Master sits in the **browser gaming + skill tracking** wedge — zero install, play in 10 seconds, share a room code with a friend. Positioning: *Premium browser chess* — Stockfish eval, ELO tracking, cloud history, polished UI that competes with Chess.com/Lichess aesthetics without their infrastructure complexity.

**Target users:** Casual players who want AI practice with rated progress, friends who want private online games, and portfolio viewers evaluating full-stack + real-time engineering depth.

**Go-to-market:** live demo at chess-livid-phi.vercel.app → GitHub → chess clubs, college gaming communities, LinkedIn posts with game review screenshots. MIT license encourages forks.

**Monetization paths (not shipped):** premium themes, unlimited cloud history, tournament brackets, spectator mode. Portfolio value is demonstrating WebSocket sync, WASM integration, ORM migrations, and OAuth in one cohesive product.

Live at chess-livid-phi.vercel.app — frontend on Vercel, API + WebSocket on Render, PostgreSQL on Neon.

**Shipped (product):** landing page with hero board · username/password + Google OAuth · game setup (local / Minimax / Stockfish / online, color, easy/med/hard, rated/casual, 3–15 min timers) · full legal chess (castling, en passant, promotion, all draw rules) · Minimax AI + Stockfish 18 WASM · live eval bar · hints & threat highlighting · online private rooms with invite links · draw offer/accept/decline · resign with correct win reason · ELO tracking (K=32, start 1200) · cloud game save + replay · game review with move quality labels · stats screen · board themes (marble/green/brown) · move list with Lichess piece icons · PGN/FEN export · resume local games · confetti on wins · mobile-responsive layout.

**Shipped (platform):** Express REST (/api/auth/*, /api/games/*) · WebSocket protocol (create/join/move/resign/draw) · Drizzle ORM + 3 SQL migrations · JWT + Google OAuth with CSRF cookie · Next.js API proxy rewrites · dev:all local orchestration.

Open source (MIT) at github.com/subhm2004/Chess.

Merge WebSocket onto single production port for simpler Render deploy. Save online games to PostgreSQL — currently only AI games persist. Add ELO for rated online matches. Streaming move analysis during play (not just post-game review). PWA for offline local/AI mode. TypeScript compile step for server instead of tsx in production. Password reset and email verification for account recovery.