Contributor Guide — Setting Up a Dev Environment
git clone https://github.com/imutkarsht/Chess_analyzer.git cd Chess_analyzer Create a virtual environment and install dependencies:
uv venv .venv source .venv/bin/activate # macOS / Linux # .venv\Scripts\activate # Windowsuv pip install -r requirements.txt Alternatively, with standard pip:
python -m venv venv source venv/bin/activate pip install -r requirements.txt uv run main.py Or with the active venv:
python main.py The app's entry point is main.py; all source code lives under src/.
Chess_analyzer/
├── main.py # Application entry point
├── requirements.txt # Dependencies
├── build.spec # PyInstaller packaging config
├── config.example.json # Template for user config
├── src/
│ ├── constants.py # App version, defaults, API URLs
│ ├── backend/
│ │ ├── analysis/ # Engine, analyzer, classifier, opening books
│ │ ├── api/ # Chess.com & Lichess API clients
│ │ ├── services/ # LLM / AI coach service (Groq, OpenAI, etc.)
│ │ ├── storage/ # SQLite database, models, PGN parser
│ │ └── updater/ # Cross-platform auto-update framework
│ ├── gui/
│ │ ├── views/ # Page views (Analyze, History, Stats, Settings)
│ │ ├── components/ # Reusable widgets
│ │ ├── analysis/ # Analysis panel widgets
│ │ ├── dialogs/ # Modal dialogs
│ │ ├── board/ # Board widget, eval bar, piece themes
│ │ └── utils/ # UI helper utilities
│ └── utils/ # Config, logger, platform paths, resources
├── tests/ # pytest test suite
├── assets/ # Images, sounds, piece SVGs, openings data
└── installers/ # Platform-specific installer scripts
The project uses pytest with pytest-qt (for PyQt6 widget testing) and pytest-mock.
# Run the full suitepython -m pytest tests/ # Run a specific test filepython -m pytest tests/test_game_load.py tests/conftest.py -shared fixtures (qapp, mock_engine, sample PGN data, temp database, temp config)tests/test_app_load.py -MainWindow initialization and page switchingtests/test_game_load.py -PGN file loading and edge casestests/backend/ -12 files covering the analyzer, engine manager, PGN parser, models, API clients, Groq service, game history, opening books, and downloadertests/gui/ -6 files covering board widget, live analysis, LLM sync, piece themes, settings view, window statetests/utils/ -2 files covering config and path utilitiesmain.python -m pytest tests/).To build a standalone executable:
pyinstaller build.spec Output goes to dist/:
ChessAnalyzerPro.appChessAnalyzerPro.exeChessAnalyzerPro binaryCopy .env.sample to .env and fill in your keys:
GROQ_API_KEY=your_groq_api_key
LICHESS_TOKEN=your_lichess_personal_token
GROQ_API_KEY -required for AI Coach features (Groq cloud)LICHESS_TOKEN -required for authenticated Lichess API requests (Opening Explorer)Open an issue on GitHub with the question label. For bug reports, include your OS, Python version, and steps to reproduce.
Download Chess Analyzer Pro for Windows, macOS, or Linux. 100% free, private, and open-source.