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.