# jtr-0901/pychess architecture

> Architecture diagram of the GitHub repository jtr-0901/pychess, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jtr-0901/pychess
- Repository: https://github.com/jtr-0901/pychess

## Overview

This is a Kivy chess app for playing against an AI or in pass-and-play timed matches, then viewing saved games. The workflow starts in the menu, selects an opponent difficulty or match time, and enters a game where the board UI submits moves to chess rules; AI moves are requested by the game screen. Completed games are saved to SQLite and surfaced in history. The excerpts show the main calls, but omit parts of the screen implementation, so some screen-to-screen and history-reading links are based on the source index rather than inspected method bodies.

Main entry points: [`ui/screens.py`](https://github.com/jtr-0901/pychess/blob/main/ui/screens.py) (Game session), [`database/history.py`](https://github.com/jtr-0901/pychess/blob/main/database/history.py) (Game records), [`main.py`](https://github.com/jtr-0901/pychess/blob/main/main.py) (Kivy app), [`ui/board.py`](https://github.com/jtr-0901/pychess/blob/main/ui/board.py) (Board and input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["App and navigation"]
  node_app["Kivy app<br/>[main.py]"]
  node_screens["Screen flows<br/>[screens.py]"]
  node_difficulty["Difficulty choice<br/>[screens.py]"]
  node_time_modes["Timed modes<br/>[screens.py]"]
end

subgraph group_gameplay["Chess gameplay"]
  node_game_screen["Game session<br/>[screens.py]"]
  node_board_ui["Board and input<br/>[board.py]"]
  node_rules["Chess rules<br/>[chess_logic.py]"]
  node_ai["AI move search<br/>[ai.py]"]
end

subgraph group_persistence["Game history"]
  node_history_screen["History view<br/>[screens.py]"]
  node_history_store["Game records<br/>[history.py]"]
  node_sqlite[("SQLite database<br/>[chess_history.db]")]
end

node_player(("Player"))

node_player -->|"launches"| node_app
node_app -->|"initializes"| node_history_store
node_app -->|"registers screens"| node_screens
node_player -->|"chooses mode"| node_screens
node_screens -->|"opens"| node_difficulty
node_screens -->|"opens"| node_time_modes
node_difficulty -->|"starts bot game"| node_game_screen
node_time_modes -->|"starts timed game"| node_game_screen
node_game_screen -->|"creates board"| node_board_ui
node_board_ui -->|"queries and submits moves"| node_rules
node_game_screen -->|"checks game state"| node_rules
node_game_screen -->|"requests move"| node_ai
node_ai -->|"returns move"| node_game_screen
node_game_screen -->|"dispatches bot move"| node_board_ui
node_game_screen -->|"saves completed game"| node_history_store
node_history_store -->|"reads and writes"| node_sqlite
node_screens -->|"opens history"| node_history_screen
node_history_screen -->|"loads records"| node_history_store

click node_app "https://github.com/jtr-0901/pychess/blob/main/main.py"
click node_screens "https://github.com/jtr-0901/pychess/blob/main/ui/screens.py"
click node_difficulty "https://github.com/jtr-0901/pychess/blob/main/ui/screens.py"
click node_time_modes "https://github.com/jtr-0901/pychess/blob/main/ui/screens.py"
click node_game_screen "https://github.com/jtr-0901/pychess/blob/main/ui/screens.py"
click node_board_ui "https://github.com/jtr-0901/pychess/blob/main/ui/board.py"
click node_rules "https://github.com/jtr-0901/pychess/blob/main/engine/chess_logic.py"
click node_ai "https://github.com/jtr-0901/pychess/blob/main/engine/ai.py"
click node_history_screen "https://github.com/jtr-0901/pychess/blob/main/ui/screens.py"
click node_history_store "https://github.com/jtr-0901/pychess/blob/main/database/history.py"
click node_sqlite "https://github.com/jtr-0901/pychess/blob/main/chess_history.db"

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_app,node_screens,node_difficulty,node_time_modes toneBlue
class node_game_screen,node_board_ui,node_rules,node_ai toneAmber
class node_history_screen,node_history_store,node_sqlite toneMint
class node_player toneIndigo
```

## Components

### App and navigation

- [Kivy app](https://github.com/jtr-0901/pychess/blob/main/main.py): `main.py`
- [Screen flows](https://github.com/jtr-0901/pychess/blob/main/ui/screens.py): `ui/screens.py`
- [Difficulty choice](https://github.com/jtr-0901/pychess/blob/main/ui/screens.py): `ui/screens.py`
- [Timed modes](https://github.com/jtr-0901/pychess/blob/main/ui/screens.py): `ui/screens.py`

### Chess gameplay

- [Game session](https://github.com/jtr-0901/pychess/blob/main/ui/screens.py): `ui/screens.py`
- [Board and input](https://github.com/jtr-0901/pychess/blob/main/ui/board.py): `ui/board.py`
- [Chess rules](https://github.com/jtr-0901/pychess/blob/main/engine/chess_logic.py): `engine/chess_logic.py`
- [AI move search](https://github.com/jtr-0901/pychess/blob/main/engine/ai.py): `engine/ai.py`

### Game history

- [History view](https://github.com/jtr-0901/pychess/blob/main/ui/screens.py): `ui/screens.py`
- [Game records](https://github.com/jtr-0901/pychess/blob/main/database/history.py): `database/history.py`
- [SQLite database](https://github.com/jtr-0901/pychess/blob/main/chess_history.db): `chess_history.db`

### Other components

- **Player**

## Connections

- Player → Kivy app: launches (evidence: `main.py`)
- Kivy app → Game records: initializes (evidence: `main.py`)
- Kivy app → Screen flows: registers screens (evidence: `main.py`)
- Player → Screen flows: chooses mode (evidence: `ui/screens.py`)
- Screen flows → Difficulty choice: opens (evidence: `ui/screens.py`)
- Screen flows → Timed modes: opens (evidence: `ui/screens.py`)
- Difficulty choice → Game session: starts bot game (evidence: `ui/screens.py`)
- Timed modes → Game session: starts timed game (evidence: `ui/screens.py`)
- Game session → Board and input: creates board (evidence: `ui/screens.py`)
- Board and input → Chess rules: queries and submits moves (evidence: `ui/board.py`)
- Game session → Chess rules: checks game state (evidence: `ui/screens.py`)
- Game session → AI move search: requests move (evidence: `ui/screens.py`)
- AI move search → Game session: returns move (evidence: `ui/screens.py`)
- Game session → Board and input: dispatches bot move (evidence: `ui/screens.py`)
- Game session → Game records: saves completed game (evidence: `ui/screens.py`)
- Game records → SQLite database: reads and writes (evidence: `database/history.py`)
- Screen flows → History view: opens history (evidence: `ui/screens.py`)
- History view → Game records: loads records (evidence: `ui/screens.py`)