Play. Learn. Improve.
A chess platform that teaches you techniques used by grandmasters through interactive lessons, adaptive practice games, and post-game analysis.
Features • Quick Start • Tech Stack • Architecture • Contributing • License
- vs Computer — Play against Stockfish (WASM) at Beginner, Intermediate, or Advanced difficulty
- vs Player — Real-time PvP with matchmaking, game clock (Bullet/Blitz/Rapid), and friend invite links
- Hints & Undo — Get Stockfish-powered hints highlighted on the board with explanations, and undo moves
- 52 Techniques — Openings, tactics, midgame strategy, and endgame mastery
- Interactive Lessons — Step-by-step walkthroughs with annotated board positions
- Practice Games — Play from realistic mid-game positions where the technique applies
- Post-Game Analysis — Move accuracy graph, evaluation bar, and key moment highlights
- Practice Queue — Puzzles generated from your mistakes with Practice Now / Save for Later / Dismiss
- Adaptive Difficulty — Engine difficulty adjusts based on your performance
- Glicko Rating — Separate rating pools for Bullet, Blitz, and Rapid
- Firebase Authentication — Sign in with Google
- Responsive Design — Works on desktop and mobile
- Guest Access — Try the platform before signing in (one free game vs computer, technique browsing)
- Node.js 20+
- PostgreSQL 16+
- Redis 7+
- Stockfish binary on PATH (for server-side analysis)
- A Firebase project with Google Authentication enabled
git clone https://github.com/codecollab-co/MyChessCoach.git
cd MyChessCoach# Create the database
createdb mychesscoach
# Push the schema
cd backend
npm install
npx drizzle-kit push
# Seed 52 chess techniques
npm run seed:techniquesBackend (backend/.env):
PORT=4000
DATABASE_URL=postgres://localhost:5432/mychesscoach
REDIS_HOST=localhost
REDIS_PORT=6379
FIREBASE_PROJECT_ID=your-firebase-project-id
FIREBASE_SERVICE_ACCOUNT_PATH=./firebase-service-account.json
STOCKFISH_PATH=stockfish
STOCKFISH_MAX_INSTANCES=4Frontend (frontend/.env):
VITE_FIREBASE_API_KEY=your-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
VITE_FIREBASE_APP_ID=your-app-id# Terminal 1 — Backend
cd backend
npm run start:dev
# Terminal 2 — Frontend
cd frontend
npm install
npm run devOpen http://localhost:3000 in your browser.
| Technology | Purpose |
|---|---|
| React + Vite | SPA framework |
| TypeScript | Type safety |
| Tailwind CSS | Styling |
| Zustand | State management |
| react-chessboard | Chess board UI |
| chess.js | Move validation, FEN/PGN |
| Stockfish WASM | In-browser chess engine |
| Socket.IO | Real-time multiplayer |
| Recharts | Analysis graphs |
| Lucide React | Icons |
| Firebase SDK | Google authentication |
| Technology | Purpose |
|---|---|
| NestJS | Modular monolith framework |
| TypeScript | Type safety |
| Drizzle ORM | Database queries + migrations |
| PostgreSQL | Primary database |
| Redis | Cache, job queue, WebSocket adapter |
| BullMQ | Async analysis jobs |
| Socket.IO | Real-time game communication |
| Stockfish (native) | Server-side deep analysis |
| Firebase Admin | Token verification |
| Passport.js | Auth guards |
┌──────────────────────────────────────────────┐
│ Frontend (SPA) │
│ React + Vite │ Stockfish WASM (Web Worker) │
│ ↕ Socket.IO ↕ REST API │
└──────────────────────────────────────────────┘
│
┌──────────────────────────────────────────────┐
│ Backend (Modular Monolith) │
│ ┌──────┐ ┌──────┐ ┌────────┐ ┌──────────┐ │
│ │ Auth │ │ Game │ │Training│ │ Analysis │ │
│ └──────┘ └──────┘ └────────┘ └──────────┘ │
│ ┌──────┐ ┌──────┐ ┌────────┐ ┌──────────┐ │
│ │Rating│ │Social│ │ Puzzle │ │ Engine │ │
│ └──────┘ └──────┘ └────────┘ └──────────┘ │
└──────────────────────────────────────────────┘
│ │ │
PostgreSQL Redis Stockfish
Each backend module is self-contained and can be extracted into a microservice by replacing direct imports with message-based communication (BullMQ/Redis pub-sub).
| Decision | Rationale |
|---|---|
| Hybrid Stockfish (WASM + native) | Zero server cost for gameplay; native binary for deep analysis |
| Modular monolith | Simple to start, ready for microservices when needed |
| Firebase for auth only | Handles OAuth complexity; all data stays in PostgreSQL |
| Glicko v1 rating | Simple, proven, used by Chess.com |
| Lichess data sources | 4M+ puzzles and comprehensive opening database — free and open |
MyChessCoach/
├── frontend/ # React + Vite SPA
│ ├── src/
│ │ ├── components/ # Reusable UI components
│ │ ├── pages/ # Route pages
│ │ ├── stores/ # Zustand state stores
│ │ ├── hooks/ # Custom hooks (useStockfish)
│ │ ├── services/ # API client, socket, auth
│ │ └── types/ # Shared TypeScript types
│ └── public/ # Static assets
├── backend/ # NestJS server
│ ├── src/
│ │ ├── modules/ # Feature modules (auth, game, training, etc.)
│ │ ├── database/ # Drizzle schema + seeds
│ │ ├── config/ # App configuration
│ │ └── common/ # Shared utilities
│ └── drizzle/ # DB migrations
└── docs/ # Project documentation
├── PROJECT_REQUIREMENTS.md
└── TECH_STACK.md
npm run dev # Start dev server (port 3000)
npm run build # Production build
npm run preview # Preview production buildnpm run start:dev # Dev server with hot reload (port 4000)
npm run build # Compile TypeScript
npm run start:prod # Production server
npm run seed:techniques # Seed 52 chess techniques
npx drizzle-kit push # Push schema to database
npx drizzle-kit generate # Generate migrations- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License — see the LICENSE file for details.
Built with ♟ by CodeCollab