Chess Opening Practice App

A full-stack chess application for practicing specific openings (Vienna Game for white, Caro-Kann for black) with AI-powered coaching feedback using Gemini API.

Features

• Practice Vienna Game (White) and Caro-Kann Defense (Black)
• Per-move AI coaching feedback on theory and intuition
• Configurable opponent difficulty (800-2800 rating)
• Real-time move validation and feedback
• Sidebar panel displaying move-by-move coaching

Tech Stack

Backend:

• FastAPI
• python-chess (Stockfish integration)
• Google Gemini API (coaching feedback)

Frontend:

• React + TypeScript
• Vite
• Tailwind CSS
• react-chessboard
• chess.js

Setup

Prerequisites

• Python 3.11+
• Node.js 20+
• Stockfish (installed via Docker or system)
• Gemini API key

Backend Setup

1. Navigate to backend directory:

cd backend

2. Create virtual environment and install dependencies:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

3. Create .env file:

cp .env.example .env

4. Add your Gemini API key to .env:

GEMINI_API_KEY=your_api_key_here
STOCKFISH_PATH=/usr/local/bin/stockfish  # Optional if Stockfish is in PATH

5. Run the backend:

uvicorn app.main:app --reload

Frontend Setup

1. Navigate to frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Run the development server:

npm run dev

The app will be available at http://localhost:5173

Docker Setup

1. Create .env file in the root directory:

GEMINI_API_KEY=your_api_key_here

2. Build and run with Docker Compose:

docker compose up --build

Backend will be at http://localhost:8000 Frontend will be at http://localhost:3000

Usage

1. Select an opening (Vienna Game or Caro-Kann Defense)
2. Choose opponent difficulty (800-2800 rating)
3. Select your color (White or Black)
4. Click "Start Game"
5. Make moves on the board
6. View per-move coaching feedback in the sidebar

API Endpoints

• POST /api/game/start - Start a new game
• POST /api/game/move - Submit a player move
• POST /api/game/opponent-move - Get opponent move
• GET /api/game/{game_id} - Get game state

License

MIT