# nishan-soni/chess-puzzles architecture

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

- Interactive diagram: https://gitdiagram.com/nishan-soni/chess-puzzles
- Repository: https://github.com/nishan-soni/chess-puzzles

## Overview

This repository turns downloaded chess games into puzzle positions, then lets a user solve those puzzles in a terminal UI. The README documents the daily retrieval, Stockfish processing, and append-to-file workflow; sampled Python source shows puzzle parsing, board rendering, and move handling. Pipeline internals were not sampled, so their documented relationships are cited to the README rather than presented as inspected implementation details.

Main entry points: [`pipeline/process_game.sh`](https://github.com/nishan-soni/chess-puzzles/blob/main/pipeline/process_game.sh) (Game processing), [`chess_puzzles.py`](https://github.com/nishan-soni/chess-puzzles/blob/main/chess_puzzles.py) (Puzzle CLI), [`pipeline/retrieve_games.sh`](https://github.com/nishan-soni/chess-puzzles/blob/main/pipeline/retrieve_games.sh) (Game retrieval), [`pipeline/pipeline.sh`](https://github.com/nishan-soni/chess-puzzles/blob/main/pipeline/pipeline.sh) (Pipeline wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Puzzle generation"]
  node_pipeline_wrapper["Pipeline wrapper<br/>[pipeline.sh]"]
  node_retrieval["Game retrieval<br/>[retrieve_games.sh]"]
  node_game_processing["Game processing<br/>[process_game.sh]"]
end

subgraph group_data["Puzzle data"]
  node_raw_games[("Downloaded games")]
  node_puzzle_file[("Puzzle positions<br/>[puzzles.txt]")]
end

subgraph group_app["Puzzle player"]
  node_cli["Puzzle CLI<br/>[chess_puzzles.py]"]
  node_loader["Puzzle loader<br/>[puzzle_loader.py]"]
  node_puzzle_state["Puzzle state<br/>[chess_puzzles.py]"]
  node_board_view["Board display<br/>[chess_puzzles.py]"]
end

node_user(("Puzzle solver"))
node_game_source["Game source"]
node_stockfish["Stockfish"]

node_pipeline_wrapper -->|"runs"| node_retrieval
node_pipeline_wrapper -->|"runs"| node_game_processing
node_retrieval -.->|"downloads games"| node_game_source
node_retrieval -.->|"stores games"| node_raw_games
node_game_processing -->|"processes games"| node_raw_games
node_game_processing -->|"analyzes with"| node_stockfish
node_game_processing -->|"appends positions"| node_puzzle_file
node_user -->|"runs"| node_cli
node_cli -->|"loads puzzles"| node_loader
node_loader -->|"reads positions"| node_puzzle_file
node_cli -->|"creates state"| node_puzzle_state
node_cli -->|"refreshes display"| node_board_view
node_puzzle_state -->|"supplies board"| node_board_view
node_user -->|"plays moves"| node_board_view

click node_pipeline_wrapper "https://github.com/nishan-soni/chess-puzzles/blob/main/pipeline/pipeline.sh"
click node_retrieval "https://github.com/nishan-soni/chess-puzzles/blob/main/pipeline/retrieve_games.sh"
click node_game_processing "https://github.com/nishan-soni/chess-puzzles/blob/main/pipeline/process_game.sh"
click node_raw_games "https://github.com/nishan-soni/chess-puzzles/tree/main/data/games_raw"
click node_puzzle_file "https://github.com/nishan-soni/chess-puzzles/blob/main/data/puzzles.txt"
click node_cli "https://github.com/nishan-soni/chess-puzzles/blob/main/chess_puzzles.py"
click node_loader "https://github.com/nishan-soni/chess-puzzles/blob/main/puzzle_loader.py"
click node_puzzle_state "https://github.com/nishan-soni/chess-puzzles/blob/main/chess_puzzles.py"
click node_board_view "https://github.com/nishan-soni/chess-puzzles/blob/main/chess_puzzles.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_pipeline_wrapper,node_retrieval,node_game_processing toneBlue
class node_raw_games,node_puzzle_file toneAmber
class node_cli,node_loader,node_puzzle_state,node_board_view toneMint
class node_user,node_game_source,node_stockfish toneIndigo
```

## Components

### Puzzle generation

- [Pipeline wrapper](https://github.com/nishan-soni/chess-puzzles/blob/main/pipeline/pipeline.sh): `pipeline/pipeline.sh`
- [Game retrieval](https://github.com/nishan-soni/chess-puzzles/blob/main/pipeline/retrieve_games.sh): `pipeline/retrieve_games.sh`
- [Game processing](https://github.com/nishan-soni/chess-puzzles/blob/main/pipeline/process_game.sh): `pipeline/process_game.sh`

### Puzzle data

- [Downloaded games](https://github.com/nishan-soni/chess-puzzles/tree/main/data/games_raw): `data/games_raw`
- [Puzzle positions](https://github.com/nishan-soni/chess-puzzles/blob/main/data/puzzles.txt): `data/puzzles.txt`

### Puzzle player

- [Puzzle CLI](https://github.com/nishan-soni/chess-puzzles/blob/main/chess_puzzles.py): `chess_puzzles.py`
- [Puzzle loader](https://github.com/nishan-soni/chess-puzzles/blob/main/puzzle_loader.py): `puzzle_loader.py`
- [Puzzle state](https://github.com/nishan-soni/chess-puzzles/blob/main/chess_puzzles.py): `chess_puzzles.py`
- [Board display](https://github.com/nishan-soni/chess-puzzles/blob/main/chess_puzzles.py): `chess_puzzles.py`

### Other components

- **Puzzle solver**
- **Game source**
- **Stockfish**

## Connections

- Pipeline wrapper → Game retrieval: runs (evidence: `README.md`)
- Pipeline wrapper → Game processing: runs (evidence: `README.md`)
- Game retrieval → Game source: downloads games
- Game retrieval → Downloaded games: stores games
- Game processing → Downloaded games: processes games (evidence: `README.md`)
- Game processing → Stockfish: analyzes with (evidence: `README.md`)
- Game processing → Puzzle positions: appends positions (evidence: `README.md`)
- Puzzle solver → Puzzle CLI: runs (evidence: `README.md`)
- Puzzle CLI → Puzzle loader: loads puzzles (evidence: `chess_puzzles.py`)
- Puzzle loader → Puzzle positions: reads positions (evidence: `puzzle_loader.py`)
- Puzzle CLI → Puzzle state: creates state (evidence: `chess_puzzles.py`)
- Puzzle CLI → Board display: refreshes display (evidence: `chess_puzzles.py`)
- Puzzle state → Board display: supplies board (evidence: `chess_puzzles.py`)
- Puzzle solver → Board display: plays moves (evidence: `chess_puzzles.py`)