# moritzhambach/detecting-cheating-in-chess architecture

> Architecture diagram of the GitHub repository moritzhambach/detecting-cheating-in-chess, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moritzhambach/detecting-cheating-in-chess
- Repository: https://github.com/moritzhambach/detecting-cheating-in-chess

## Overview

This repository is a chess-game engine-use classifier. Its main workflow takes a PGN game, prepares board-position and attack tensors, and applies a color-specific trained model to estimate whether the opponent used an engine. A separate data workflow converts game archives, filters and balances labeled games, encodes them, and trains several model architectures. The README also documents heatmap exploration. Relationships are limited to calls visible in excerpts or workflow statements in the README; DVC stage internals were not sampled.

Main entry points: [`python_code/moves_to_fen.py`](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/moves_to_fen.py) (Board and attack tensors), [`python_code/make_prediction.py`](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/make_prediction.py) (Prediction command), [`models`](https://github.com/moritzhambach/detecting-cheating-in-chess/tree/master/models) (Trained models), [`python_code/preprocess.py`](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/preprocess.py) (Game filtering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Game ingestion"]
  node_pgnjson["PGN to JSON<br/>[pgn_to_json.py]"]
  node_filter["Game filtering<br/>[preprocess.py]"]
  node_evalmoves["Evaluation moves<br/>[eval_get_moves.py]"]
end

subgraph group_features["Game features"]
  node_moveencoding["Move to FEN<br/>[moves_to_fen.py]"]
  node_pgnfen["PGN to FEN<br/>[pgn_to_fen.py]"]
  node_tensor["Board and attack tensors<br/>[moves_to_fen.py]"]
  node_params["Preprocess parameters"]
  node_heatmaps["Heatmap exploration"]
end

subgraph group_learning["Model training"]
  node_cnn["CNN-LSTM training<br/>[train_CNN_LSTM.py]"]
  node_conv3d["Conv3D training<br/>[train_Conv3D.py]"]
  node_fclstm["Dense-LSTM training"]
  node_models[("Trained models")]
end

subgraph group_inference["Game classification"]
  node_evalstage["Evaluation preparation"]
  node_predict["Prediction command<br/>[make_prediction.py]"]
end

node_archive(("PGN archives"))
node_player(("Game submitter"))
node_probability["Engine-use probability"]

node_archive -->|"supplies games"| node_pgnjson
node_pgnjson -->|"provides game data"| node_filter
node_filter -.->|"selects labeled games"| node_tensor
node_moveencoding -->|"calls converter"| node_pgnfen
node_moveencoding -->|"encodes positions"| node_tensor
node_filter -->|"reads settings"| node_params
node_tensor -.->|"supports exploration"| node_heatmaps
node_tensor -->|"trains on tensors"| node_cnn
node_tensor -->|"trains on tensors"| node_conv3d
node_tensor -->|"trains on tensors"| node_fclstm
node_cnn -->|"saves model"| node_models
node_conv3d -->|"saves model"| node_models
node_fclstm -->|"saves model"| node_models
node_player -->|"submits PGN"| node_evalstage
node_evalstage -->|"prepares evaluation"| node_predict
node_models -->|"loads color model"| node_predict
node_predict -->|"reads settings"| node_params
node_predict -->|"reports estimate"| node_probability
node_evalmoves -.->|"prepares move data"| node_evalstage

click node_pgnjson "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/pgn_to_json.py"
click node_filter "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/preprocess.py"
click node_evalmoves "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/eval_get_moves.py"
click node_moveencoding "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/moves_to_fen.py"
click node_pgnfen "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/pgn_to_fen.py"
click node_tensor "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/moves_to_fen.py"
click node_params "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/configs/preprocess_params.json"
click node_heatmaps "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/data_exploration_and_heatmaps.ipynb"
click node_cnn "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/train_CNN_LSTM.py"
click node_conv3d "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/train_Conv3D.py"
click node_fclstm "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/train_Fully_Connected_LSTM.py"
click node_models "https://github.com/moritzhambach/detecting-cheating-in-chess/tree/master/models"
click node_evalstage "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/dvc-stages/eval_moves_to_fen.dvc"
click node_predict "https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/make_prediction.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pgnjson,node_filter,node_evalmoves toneBlue
class node_moveencoding,node_pgnfen,node_tensor,node_params,node_heatmaps toneAmber
class node_cnn,node_conv3d,node_fclstm,node_models toneMint
class node_evalstage,node_predict toneRose
class node_archive,node_player,node_probability toneIndigo
```

## Components

### Game ingestion

- [PGN to JSON](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/pgn_to_json.py): `python_code/pgn_to_json.py`
- [Game filtering](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/preprocess.py): `python_code/preprocess.py`
- [Evaluation moves](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/eval_get_moves.py): `python_code/eval_get_moves.py`

### Game features

- [Move to FEN](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/moves_to_fen.py): `python_code/moves_to_fen.py`
- [PGN to FEN](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/pgn_to_fen.py): `python_code/pgn_to_fen.py`
- [Board and attack tensors](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/moves_to_fen.py): `python_code/moves_to_fen.py`
- [Preprocess parameters](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/configs/preprocess_params.json): `configs/preprocess_params.json`
- [Heatmap exploration](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/data_exploration_and_heatmaps.ipynb): `data_exploration_and_heatmaps.ipynb`

### Model training

- [CNN-LSTM training](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/train_CNN_LSTM.py): `python_code/train_CNN_LSTM.py`
- [Conv3D training](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/train_Conv3D.py): `python_code/train_Conv3D.py`
- [Dense-LSTM training](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/train_Fully_Connected_LSTM.py): `python_code/train_Fully_Connected_LSTM.py`
- [Trained models](https://github.com/moritzhambach/detecting-cheating-in-chess/tree/master/models): `models`

### Game classification

- [Evaluation preparation](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/dvc-stages/eval_moves_to_fen.dvc): `dvc-stages/eval_moves_to_fen.dvc`
- [Prediction command](https://github.com/moritzhambach/detecting-cheating-in-chess/blob/master/python_code/make_prediction.py): `python_code/make_prediction.py`

### Other components

- **PGN archives**
- **Game submitter**
- **Engine-use probability**

## Connections

- PGN archives → PGN to JSON: supplies games (evidence: `README.md`)
- PGN to JSON → Game filtering: provides game data (evidence: `README.md`)
- Game filtering → Board and attack tensors: selects labeled games
- Move to FEN → PGN to FEN: calls converter (evidence: `python_code/moves_to_fen.py`)
- Move to FEN → Board and attack tensors: encodes positions (evidence: `python_code/moves_to_fen.py`)
- Game filtering → Preprocess parameters: reads settings (evidence: `python_code/preprocess.py`)
- Board and attack tensors → Heatmap exploration: supports exploration
- Board and attack tensors → CNN-LSTM training: trains on tensors (evidence: `python_code/train_CNN_LSTM.py`)
- Board and attack tensors → Conv3D training: trains on tensors (evidence: `python_code/train_Conv3D.py`)
- Board and attack tensors → Dense-LSTM training: trains on tensors (evidence: `python_code/train_Fully_Connected_LSTM.py`)
- CNN-LSTM training → Trained models: saves model (evidence: `python_code/train_CNN_LSTM.py`)
- Conv3D training → Trained models: saves model (evidence: `python_code/train_Conv3D.py`)
- Dense-LSTM training → Trained models: saves model (evidence: `python_code/train_Fully_Connected_LSTM.py`)
- Game submitter → Evaluation preparation: submits PGN (evidence: `README.md`)
- Evaluation preparation → Prediction command: prepares evaluation (evidence: `README.md`)
- Trained models → Prediction command: loads color model (evidence: `python_code/make_prediction.py`)
- Prediction command → Preprocess parameters: reads settings (evidence: `python_code/make_prediction.py`)
- Prediction command → Engine-use probability: reports estimate (evidence: `python_code/make_prediction.py`)
- Evaluation moves → Evaluation preparation: prepares move data
