Free, open-source chess analysis, training, and improvement platform powered by Stockfish
EloInsight democratizes chess game analysis by providing a completely free, open-source platform that rivals premium chess analysis tools. We believe every chess player, regardless of their financial situation, deserves access to powerful game analysis tools to improve their skills.
- 🔗 Multi-Platform Integration: Link your Chess.com and Lichess accounts
- 🔐 Social Login: Sign in with Lichess or Google OAuth
- 📥 Automatic Game Sync: Fetch and analyze all your completed games automatically
- 🤖 Free Stockfish Analysis: Powered by the world's strongest open-source chess engine (depth 20)
- 📊 Comprehensive Metrics:
- Accuracy percentage for both players
- Average Centipawn Loss (ACPL)
- Blunders, mistakes, and inaccuracies detection
- Performance rating calculation ("You played like a XXXX")
- 📈 Phase Breakdown: Move quality breakdown by game phase (Opening/Middlegame/Endgame) with visual icons
- 📉 Evaluation Graph: Interactive game evaluation chart with click-to-navigate
- 🎯 Key Moments: Auto-detected critical positions (blunders, turning points, brilliant moves)
- 📊 Win Probability: Real-time win/draw/loss probability bar
- 🔍 Engine Lines (PV): Top engine continuations with evaluations
- 💡 Suggested Focus Areas: AI-powered study recommendations based on your mistakes
- ⏱️ Time Analysis: Time spent per move with statistics
- 🔗 Similar Games: Quick links to explore positions on Lichess/Chess.com
- 🎮 Exploration Mode: Make moves on the board to analyze alternative lines
▶️ Auto-play Mode: Automatically advance through moves with adjustable speed (0.5s - 3s)- 🔊 Move Sounds: Audio feedback for moves, captures, checks, and blunders
- ⌨️ Keyboard Shortcuts: Full keyboard navigation (arrows, space, F, C, M, ?)
- 📋 Copy FEN: One-click FEN copying for any position
- 🔄 Board Flip: View from either player's perspective
- 🎯 Manual Analysis: Analyze any position using FEN notation
- 📈 Progress Tracking: Track your improvement over time
- 🔍 Advanced Filtering: Filter games by platform, result, time control, analysis status, and date
- 📄 Pagination: Efficient browsing of large game collections
- 🧩 Chess Puzzles: Solve tactical puzzles with a built-in interactive board
- Practice and Challenge modes (unlimited retries vs. one-strike-out)
- Import the full Lichess puzzle database (~4M puzzles, 1 GB CSV streamed efficiently)
- Filter by rating range (400–2800), themes (fork, pin, mate-in-1, etc.), and depth
- Hints system, streak tracking, and per-session statistics
- Keyboard shortcuts (N = next, H = hint, R = retry, Enter = start/next)
- 🧠 Memory Training: Memorize and recreate random piece positions on the board
- Configurable piece count (1–16), memorization time (3–30s), and piece colors
- Normal mode (exact pieces provided) and Hard mode (full piece palette)
- Drag-and-drop or click-to-place recall interface
- Accuracy scoring with per-square feedback (correct / missed / wrong piece)
- Streak and best-streak tracking
- 📊 Dashboard: Overview stats, user management, and activity monitoring
- 👥 User Management: Create, update, soft-delete, and restore users
- ♟️ Game Management: View, edit, delete games; requeue analysis; fix Lichess data
- 🔗 Linked Accounts: Manage platform connections
- 🔄 Sync & Analysis Jobs: Monitor, cancel, retry sync and analysis jobs
- 📈 Statistics: Per-user statistics and opening statistics; trigger recalculation
- Opening repertoire analysis
- Tournament preparation tools
- Social features and game sharing
- Board themes and piece styles
- Mobile app
- React 18 with TypeScript
- Vite for fast development and building
- TailwindCSS for utility-first styling
- Recharts for evaluation graphs and data visualization
- React Router v6 for navigation
- Lucide React for icons
- react-chessboard for interactive chess board
- chess.js for move validation and game logic
- NestJS (API Gateway - TypeScript)
- Go (Analysis Service with Stockfish integration)
- NestJS (Game Sync Service - TypeScript)
- PostgreSQL - Primary database with Prisma ORM
- Redis - Caching and session management
- Docker - Containerization
- Docker Compose - Local development orchestration
- REST API - Frontend to API Gateway
- gRPC - API Gateway to Analysis Service
- JWT - Authentication tokens
- OAuth 2.0 - Lichess and Google authentication
EloInsight follows a microservices architecture for scalability and maintainability:
┌─────────────────┐
│ React Frontend │
└────────┬────────┘
│ REST API
▼
┌─────────────────┐
│ API Gateway │
│ (NestJS) │
└────────┬────────┘
│ gRPC
┌────┴────┬──────────┬──────────┐
▼ ▼ ▼ ▼
┌────────┐ ┌──────┐ ┌─────────┐ ┌──────────┐
│ User │ │ Game │ │Analysis │ │Metadata │
│Service │ │Sync │ │ Engine │ │ Service │
│(NestJS)│ │(Go) │ │ (Go) │ │ (Python) │
└────────┘ └──────┘ └─────────┘ └──────────┘
│ │ │ │
└─────────┴──────────┴────────────┘
│
┌──────┴──────┐
▼ ▼
┌──────────┐ ┌───────┐
│PostgreSQL│ │ Redis │
└──────────┘ └───────┘
For detailed architecture documentation, see docs/architecture.md.
# Clone the repository
git clone https://github.com/yourusername/EloInsight.git
cd EloInsight
# Copy environment file
cp .env.example .env
# Start everything with one command
make devThat's it! 🎉 All services will start with hot reloading enabled.
| Service | URL |
|---|---|
| Frontend | http://localhost:13000 |
| Admin Panel | http://localhost:13001 |
| API Gateway | http://localhost:14000/api/v1 |
| Swagger Docs | http://localhost:14000/api/docs |
| Game Sync | http://localhost:14002 |
make help # Show all commands
make dev # Start development stack
make down # Stop all containers
make logs # View all logs
make db-migrate # Run database migrations
make db-seed # Seed sample dataClick to expand manual setup instructions
- Node.js >= 18.x
- Go >= 1.21
- PostgreSQL >= 15
- Redis >= 7.0
- Stockfish chess engine
-
Start infrastructure services
docker-compose -f docker-compose.dev.yml up -d postgres redis
-
Install dependencies and start services
Frontend:
cd frontend && npm install && npm run dev
API Gateway:
cd backend/api-gateway && npm install && npm run start:dev
Game Sync Service:
cd backend/game-sync-service && npm install && npm run start:dev
Analysis Engine:
cd backend/analysis-service && make build && ./bin/analysis-service
For detailed setup instructions, see docs/local-setup.md.
- Local Development Setup
- Architecture Overview
- System Design
- Services Documentation
- Tech Stack Details
- API Design
- gRPC Design
- Database Design
- Analysis Engine
- Stockfish Integration
- Game Synchronization
- Security
- Deployment Guide
- Roadmap
- Contributing
- FAQ
We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.
Please read our Contributing Guide to get started.
This project is licensed under the MIT License - see the LICENSE file for details.
- Stockfish - The powerful chess engine that powers our analysis
- Chess.com - For their public API
- Lichess - For their excellent open API
- All our contributors and supporters
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Made with ♟️ by chess players, for chess players