Architecture
Setup & Usage9
Project2
How the Qt-free backend, the PyQt6 interface, and SQLite storage fit together.
Chess Analyzer Pro keeps a strict boundary between a Qt-free backend and a PyQt6 presentation layer.
The GUI renders state and dispatches actions; analysis, storage, classification, and networking live
in src/backend/.
main.py
└── src/gui/** presentation (PyQt6)
└── src/backend/** domain logic, zero Qt imports
└── src/utils/**, src/constants.py leaf helpers
Allowed dependencies:
| Layer | May import |
|---|---|
gui | backend, utils, config, constants |
backend | utils, constants, config schema |
config | constants |
utils | constants only |
Forbidden:
backend importing PyQt6 or anything under src.guiutils importing GUI codesrc.gui.components.<subpackage> directly instead of the facadeMainWindow (gui/main_window/window.py)
├── mixins: navigation · analysis · loading · theme · tour · update · variation · status
├── Sidebar + FadedStackedWidget
└── pages
├── AnalysisView → AnalysisPanel, MoveListPanel, Board, VariationMode, EngineLinesWidget
│ └── CoachCardWidget → ExplainMoveWorker → GroqService
├── ExplorerView
├── HistoryView → GamesRepo / cache repositories
├── MetricsView → StatsWorker → metrics aggregation
└── SettingsView → settings_schema → ConfigManager → config.json / SecretStore
QThread worker → Analyzer → EngineManager → Stockfish (UCI)
QThread worker → Chess.com / Lichess clients → HTTPS
Analyzer → AnalysisCache → SQLite (analysis_cache.db)
Every blocking task runs in a QThread and reports through pyqtSignal. The engine is stopped in a
finally block, and a new analysis restarts it rather than assuming it is running.
| Area | Responsibility |
|---|---|
src/backend/analysis | Engine orchestration, classification, metrics, tactics, variations, opening data |
src/backend/api | Chess.com and Lichess REST clients, import limits |
src/backend/cache | API response cache facade |
src/backend/engine | Stockfish download and binary validation |
src/backend/models | Lightweight cross-layer models such as GameInfo |
src/backend/services | LLM and feedback integrations |
src/backend/storage | Schema, repositories, migrations, PGN parsing, backup |
src/backend/updater | GitHub release checks and platform installers |
src/config | Settings metadata, defaults, and validation (Qt-free) |
src/gui/main_window | Window composition and cross-cutting mixins |
src/gui/views | Pages and their sub-widgets (metrics/, settings/, …) |
src/gui/analysis | Analysis panel, move list, Coach, variations, live engine |
src/gui/board | SVG board, arrows, eval bar, piece themes |
src/gui/components | Shared component library, grouped by responsibility |
src/gui/dialogs | Load game, wizard, feedback, errors, updates |
src/gui/theme, styles.py | Palettes, tokens, motion, QSS generators |
src/utils | Config, logging, paths, resources, secrets |
GameLoadingMixin.load_game() receives a GameAnalysis and hands it to the analysis page.AnalysisMixin.start_analysis() starts AnalysisWorker, which drives Analyzer.analyze_game().Analyzer calls EngineManager per position, checks AnalysisCache, and converts every score to
White's perspective once during ingestion.AnalysisPanel renders
accuracy, charts, and the Coach tab.LiveEngineSession owns one Stockfish process and the current FEN.EngineLinesWidget in Analyze and Explore.StatusBarMixin.MainWindow.closeEvent().LoadGameDialog hosts the panels in gui/dialogs/load_game/.ApiWorker performs network work off the UI thread.ChessComAPI and LichessAPI normalize results into GameInfo and GameAnalysis.PGNParser handles files and text; GameImportWorker handles CSV.GameHistoryManager into GamesRepo and the cache repositories.CoachCardWidget builds the offline summary immediately from backend/analysis/tactics/insight.py.ExplainMoveWorker, which sends the fact dossier to GroqService.move_explanations; on failure the offline text stays visible.backend/analysis/game_report.py and are saved with the game.VariationMode.VariationMode mutates a FEN-keyed tree in backend/analysis/variation_tree.py.src/config/settings_schema.py defines every setting's type, default, tier, and validation.SettingsView builds category cards using SettingsForm and the settings binder.ConfigManager persists JSON; SecretStore keeps credentials in the OS keychain.apply="live" settings update immediately; others apply on save or restart.HistoryView builds a GameQuery from debounced filters.GamesRepo returns one page (10 detailed or 15 compact).PaginationBar and GameListWidget share the paging state.| Invariant | Rule |
|---|---|
| Offline first | Analysis, Stockfish, PGN parsing, openings, and history work with no network |
| Threading | Engine, imports, LLM, backup, and stats never block the UI thread |
| White-perspective scores | Scores are converted once in Analyzer._process_analysis_results(); widgets never flip |
| Thermal safety | multi_pv=2, engine_threads=1, engine_hash=128 MB; the UI recommends at most min(cpu_count, 4) threads |
| Deterministic identity | game_id = md5(pgn_content), so re-imports update instead of duplicating |
| Accuracy floor | Per-move accuracy never drops below 10% |
| Chess960 | Non-standard castling tags enable UCI_Chess960 and chess960=True boards |
| Theming | Per-widget styles rebuild from the live palette; colors are never captured at construction |
| Concern | Location |
|---|---|
| Settings | src/config/settings_schema.py |
| SQL columns | GAME_COLUMNS and GAME_CSV_COLUMNS |
| Serialization | MoveAnalysis.to_dict() and from_dict() |
| Shared controls | the src.gui.components facade |
| Directory | Contents |
|---|---|
assets/icons/ | Sidebar and toolbar icons |
assets/images/ | Classification icons, logo, time-control icons |
assets/pieces/ | Cburnett SVG piece set |
assets/openings/ | Lichess ECO TSV files (a.tsv–e.tsv) |
assets/sounds/ | Move, capture, check, castle, and game-end sounds |
For the file-by-file reference, see the repository's
docs/architecture.md.
Download Chess Analyzer Pro for Windows, macOS, or Linux. 100% free, private, and open-source.