Files & Data Structure
Chess Analyzer Pro manages several auto-generated files to maintain your settings and data locally.
Auto-Generated Files
The application automatically creates and manages configurations, cache, and logs inside standard platform-specific directories to keep your application folders clean:
- macOS:
~/Library/Application Support/ChessAnalyzerPro - Windows:
%APPDATA%/ChessAnalyzerPro - Linux:
~/.local/share/chessanalyzerpro
| File Name | Location | Description |
|---|---|---|
config.json | User Data Dir | User Settings. JSON file storing settings, theme configurations, and LLM active profiles. |
analysis_cache.db | User Data Dir | Local Database. A SQLite database storing the engine analysis cache (analysis table) and game history (games table). |
chess_analyzer.log | User Data Dir | Debug Logs. Captures runtime events and system warnings. |
games.csv | User Selected | Exported Data. Created only if you choose to export your history (saved to a location of your choice). |
Database Schema (analysis_cache.db)
The SQLite database contains two main tables:
analysis - Engine Analysis Cache
Stores engine evaluations of chess positions to avoid duplicate calculations.
| Column | Type | Description |
|---|---|---|
id | TEXT | SHA-256 hash of FEN + multi_pv configuration (primary key) |
fen | TEXT | Chess position in FEN format |
engine_params | TEXT | JSON string of engine configurations (depth, multi_pv, threads) |
depth | INTEGER | Engine search depth at which position was evaluated |
result | TEXT | Serialized JSON of engine outputs (top principal variations, CP, mates) |
games - Game History
Preserves your complete history of analyzed chess games.
| Column | Type | Description |
|---|---|---|
id | TEXT | Unique game identifier (primary key) |
white | TEXT | White player name |
black | TEXT | Black player name |
result | TEXT | Game outcome (e.g. 1-0, 0-1, 1/2-1/2) |
date | TEXT | Date of the game |
event | TEXT | Event/Tournament name |
pgn | TEXT | Full PGN text including move list and analysis comments |
summary_json | TEXT | Serialized JSON containing players' accuracy, blunders, and other stats |
timestamp | REAL | Epoch timestamp representing when the game was saved |
white_elo | TEXT | Rating of the White player |
black_elo | TEXT | Rating of the Black player |
time_control | TEXT | Time control of the match |
eco | TEXT | ECO code for the opening |
termination | TEXT | Termination reason (e.g., checkmate, resignation, time out) |
opening | TEXT | Name of the opening variation played |
starting_fen | TEXT | Starting position FEN (if non-standard, like Chess960) |
source | TEXT | Origin of import (chesscom, lichess, file) |
Inspecting Your Data
Analysis Cache & Game History (analysis_cache.db)
This SQLite database ensures you never have to wait for the same analysis twice and preserves your complete game library.
[!TIP] Recommended Tool: Use Beekeeper Studio (Community Edition) or DB Browser for SQLite to open and inspect the database.
Configuration (config.json)
You can manually edit this file if needed, but it is recommended to use the in-app Settings menu to avoid syntax errors.
Example config.json:
{
"engine_path": "stockfish",
"theme": "dark",
"sound_enabled": true,
"lichess_token": "lip_...",
"lichess_username": "DrNykterstein",
"chesscom_username": "MagnusCarlsen",
"accent_color": "#4CAF50",
"board_theme": "default",
"piece_theme": "cburnett",
"analysis_depth": 18,
"api_games_limit": 20,
"multi_pv": 1,
"live_analysis_time": 2.0,
"llm_profiles": [
{
"name": "Groq",
"provider": "groq",
"api_key": "gsk_...",
"model": "llama-3.3-70b-versatile",
"base_url": ""
}
],
"llm_active_profile": "Groq"
}
Debug Logs (chess_analyzer.log)
Check this file for error messages and application events:
# View the last 50 lines
tail -50 chess_analyzer.log
# Windows PowerShell
Get-Content chess_analyzer.log -Tail 50
Environment Variables (.env)
For development, you can use a .env file to store API keys instead of config.json:
GROQ_KEY=your_groq_api_key
LICHESS_TOKEN=your_lichess_token
[!NOTE] The
.envfile is only used during development. The packaged.exereads fromconfig.json.
Data Backup & Restore
Export to CSV
- Go to History tab.
- Click the Export button (or use menu).
- Choose a save location for
games.csv. - All game metadata and summaries are exported.
Import from CSV
- Go to History tab.
- Click the Import button.
- Select your previously exported
games.csv. - Games are restored to your history (duplicates are skipped).
Data Privacy
- 100% Local: All files listed above stay on your machine.
- No Cloud Storage: We do not upload your games, keys, or logs to any server.
- No Telemetry: The application does not collect or transmit any usage data.
- Your Keys Are Safe: API keys are stored locally in
config.jsonand are never shared.
The only network requests made by the application are:
- Fetching games from Chess.com/Lichess APIs (when you request it).
- Calling the Groq API for AI summaries (when you request it).