Files & Data Structure

Chess Analyzer Pro manages several auto-generated files to maintain your settings and data locally.

Auto-Generated Files

The application creates these files in the root directory (where the .exe or main.py is located).

File Name	Description
`config.json`	User Settings. JSON file storing your Engine Path, API Keys, Usernames, Theme preferences, Board Theme, and Piece Theme.
`analysis_cache.db`	Local Database. A SQLite database that stores both the position analysis cache AND your complete game history with all analysis data.
`chess_analyzer.log`	Debug Logs. A text file capturing application events and errors for troubleshooting.
`games.csv`	Exported Data. Only exists if you've used the Export feature. Contains your game history in CSV format for backup.

Database Schema (`analysis_cache.db`)

The SQLite database contains two main tables:

`position_cache` - Analysis Cache

Stores engine analysis results by position to avoid re-analyzing.

Column	Type	Description
`fen`	TEXT	Position in FEN notation (primary key)
`eval_cp`	INTEGER	Evaluation in centipawns
`eval_mate`	INTEGER	Mate distance (if forced mate)
`best_move`	TEXT	Engine's best move (UCI)
`pv`	TEXT	Principal variation (JSON)
`depth`	INTEGER	Analysis depth

`games` - Game History

Stores complete analyzed games with all metadata.

Column	Type	Description
`game_id`	TEXT	Unique identifier (primary key)
`white`	TEXT	White player name
`black`	TEXT	Black player name
`white_elo`	TEXT	White player rating
`black_elo`	TEXT	Black player rating
`result`	TEXT	Game result (1-0, 0-1, 1/2-1/2)
`date`	TEXT	Game date
`event`	TEXT	Event name
`eco`	TEXT	ECO opening code
`opening`	TEXT	Opening name
`termination`	TEXT	How the game ended
`source`	TEXT	Origin (file, chesscom, lichess)
`pgn`	TEXT	Full PGN text
`moves_json`	TEXT	Serialized move analysis data
`summary_json`	TEXT	Serialized game summary stats
`timestamp`	REAL	When the game was saved

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/stockfish.exe",
    "theme": "dark",
    "gemini_api_key": "AIza...",
    "lichess_token": "lip_...",
    "lichess_username": "DrNykterstein",
    "chesscom_username": "MagnusCarlsen",
    "accent_color": "#4CAF50",
    "board_theme": "default",
    "piece_theme": "cburnett"
}

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:

GEMINI_KEY=your_gemini_api_key
LICHESS_TOKEN=your_lichess_token

[!NOTE] The .env file is only used during development. The packaged .exe reads from config.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.json and are never shared.

The only network requests made by the application are:

Fetching games from Chess.com/Lichess APIs (when you request it).
Calling Google Gemini API for AI summaries (when you request it).

Files & Data Structure

Chess Analyzer Pro manages several auto-generated files to maintain your settings and data locally.

Auto-Generated Files

The application creates these files in the root directory (where the .exe or main.py is located).

File Name	Description
`config.json`	User Settings. JSON file storing your Engine Path, API Keys, Usernames, Theme preferences, Board Theme, and Piece Theme.
`analysis_cache.db`	Local Database. A SQLite database that stores both the position analysis cache AND your complete game history with all analysis data.
`chess_analyzer.log`	Debug Logs. A text file capturing application events and errors for troubleshooting.
`games.csv`	Exported Data. Only exists if you've used the Export feature. Contains your game history in CSV format for backup.

Database Schema (`analysis_cache.db`)

The SQLite database contains two main tables:

`position_cache` - Analysis Cache

Stores engine analysis results by position to avoid re-analyzing.

Column	Type	Description
`fen`	TEXT	Position in FEN notation (primary key)
`eval_cp`	INTEGER	Evaluation in centipawns
`eval_mate`	INTEGER	Mate distance (if forced mate)
`best_move`	TEXT	Engine's best move (UCI)
`pv`	TEXT	Principal variation (JSON)
`depth`	INTEGER	Analysis depth

`games` - Game History

Stores complete analyzed games with all metadata.

Column	Type	Description
`game_id`	TEXT	Unique identifier (primary key)
`white`	TEXT	White player name
`black`	TEXT	Black player name
`white_elo`	TEXT	White player rating
`black_elo`	TEXT	Black player rating
`result`	TEXT	Game result (1-0, 0-1, 1/2-1/2)
`date`	TEXT	Game date
`event`	TEXT	Event name
`eco`	TEXT	ECO opening code
`opening`	TEXT	Opening name
`termination`	TEXT	How the game ended
`source`	TEXT	Origin (file, chesscom, lichess)
`pgn`	TEXT	Full PGN text
`moves_json`	TEXT	Serialized move analysis data
`summary_json`	TEXT	Serialized game summary stats
`timestamp`	REAL	When the game was saved

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/stockfish.exe",
    "theme": "dark",
    "gemini_api_key": "AIza...",
    "lichess_token": "lip_...",
    "lichess_username": "DrNykterstein",
    "chesscom_username": "MagnusCarlsen",
    "accent_color": "#4CAF50",
    "board_theme": "default",
    "piece_theme": "cburnett"
}

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:

GEMINI_KEY=your_gemini_api_key
LICHESS_TOKEN=your_lichess_token

[!NOTE] The .env file is only used during development. The packaged .exe reads from config.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.json and are never shared.

The only network requests made by the application are:

Fetching games from Chess.com/Lichess APIs (when you request it).
Calling Google Gemini API for AI summaries (when you request it).

Files & Data Structure

Auto-Generated Files

Database Schema (analysis_cache.db)

position_cache - Analysis Cache

games - Game History

Inspecting Your Data

Analysis Cache & Game History (analysis_cache.db)

Configuration (config.json)

Debug Logs (chess_analyzer.log)

Environment Variables (.env)

Data Backup & Restore

Export to CSV

Import from CSV

Data Privacy

Files & Data Structure

Auto-Generated Files

Database Schema (analysis_cache.db)

position_cache - Analysis Cache

games - Game History

Inspecting Your Data

Analysis Cache & Game History (analysis_cache.db)

Configuration (config.json)

Debug Logs (chess_analyzer.log)

Environment Variables (.env)

Data Backup & Restore

Export to CSV

Import from CSV

Data Privacy

Database Schema (`analysis_cache.db`)

`position_cache` - Analysis Cache

`games` - Game History

Analysis Cache & Game History (`analysis_cache.db`)

Configuration (`config.json`)

Debug Logs (`chess_analyzer.log`)

Environment Variables (`.env`)

Database Schema (`analysis_cache.db`)

`position_cache` - Analysis Cache

`games` - Game History

Analysis Cache & Game History (`analysis_cache.db`)

Configuration (`config.json`)

Debug Logs (`chess_analyzer.log`)

Environment Variables (`.env`)