# icyss999/hang-man-python architecture

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

- Interactive diagram: https://gitdiagram.com/icyss999/hang-man-python
- Repository: https://github.com/icyss999/hang-man-python

## Overview

This is a terminal Hangman game: players select a category, guess a word, and can view a top-10 leaderboard. The menu in `app/main.py` orchestrates play and leaderboard actions; `utils/game_track.py` manages rounds, while `utils/gui.py` renders screens. Successful rounds and player names are persisted through the leaderboard layer to SQLite. The README documents how to launch the app but no additional product capabilities. The graph follows the sampled calls; database schema creation is shown, but no runtime connection to the migrations or mock-data directory is evidenced.

Main entry points: [`app/main.py`](https://github.com/icyss999/hang-man-python/blob/main/app/main.py) (Game menu), [`utils/game_track.py`](https://github.com/icyss999/hang-man-python/blob/main/utils/game_track.py) (Guessing round), [`utils/leaderboard.py`](https://github.com/icyss999/hang-man-python/blob/main/utils/leaderboard.py) (Leaderboard logic), [`utils/word_bank.py`](https://github.com/icyss999/hang-man-python/blob/main/utils/word_bank.py) (Category selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Game interaction"]
  node_menu["Game menu<br/>[main.py]"]
  node_categories["Category selection<br/>[word_bank.py]"]
  node_round["Guessing round<br/>[game_track.py]"]
end

subgraph group_presentation["Terminal presentation"]
  node_screens["Game screens<br/>[gui.py]"]
  node_format["Time formatting<br/>[gui.py]"]
end

subgraph group_records["Player records"]
  node_leaderboard["Leaderboard logic<br/>[leaderboard.py]"]
  node_sqlite[("SQLite database<br/>[index.py]")]
end

node_player(("Player"))

node_player -->|"chooses action"| node_menu
node_menu -->|"chooses word"| node_categories
node_menu -->|"starts round"| node_round
node_round -->|"renders screens"| node_screens
node_player -->|"enters guesses"| node_round
node_round -->|"returns result"| node_menu
node_menu -->|"stores player"| node_leaderboard
node_menu -->|"stores result"| node_leaderboard
node_menu -->|"requests rankings"| node_leaderboard
node_leaderboard -->|"reads and writes"| node_sqlite
node_menu -->|"formats times"| node_format

click node_menu "https://github.com/icyss999/hang-man-python/blob/main/app/main.py"
click node_categories "https://github.com/icyss999/hang-man-python/blob/main/utils/word_bank.py"
click node_round "https://github.com/icyss999/hang-man-python/blob/main/utils/game_track.py"
click node_screens "https://github.com/icyss999/hang-man-python/blob/main/utils/gui.py"
click node_format "https://github.com/icyss999/hang-man-python/blob/main/utils/gui.py"
click node_leaderboard "https://github.com/icyss999/hang-man-python/blob/main/utils/leaderboard.py"
click node_sqlite "https://github.com/icyss999/hang-man-python/blob/main/db/index.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_menu,node_categories,node_round toneBlue
class node_screens,node_format toneAmber
class node_leaderboard,node_sqlite toneMint
class node_player toneIndigo
```

## Components

### Game interaction

- [Game menu](https://github.com/icyss999/hang-man-python/blob/main/app/main.py): `app/main.py`
- [Category selection](https://github.com/icyss999/hang-man-python/blob/main/utils/word_bank.py): `utils/word_bank.py`
- [Guessing round](https://github.com/icyss999/hang-man-python/blob/main/utils/game_track.py): `utils/game_track.py`

### Terminal presentation

- [Game screens](https://github.com/icyss999/hang-man-python/blob/main/utils/gui.py): `utils/gui.py`
- [Time formatting](https://github.com/icyss999/hang-man-python/blob/main/utils/gui.py): `utils/gui.py`

### Player records

- [Leaderboard logic](https://github.com/icyss999/hang-man-python/blob/main/utils/leaderboard.py): `utils/leaderboard.py`
- [SQLite database](https://github.com/icyss999/hang-man-python/blob/main/db/index.py): `db/index.py`

### Other components

- **Player**

## Connections

- Player → Game menu: chooses action (evidence: `app/main.py`)
- Game menu → Category selection: chooses word (evidence: `app/main.py`)
- Game menu → Guessing round: starts round (evidence: `app/main.py`)
- Guessing round → Game screens: renders screens (evidence: `utils/game_track.py`)
- Player → Guessing round: enters guesses (evidence: `utils/game_track.py`)
- Guessing round → Game menu: returns result (evidence: `app/main.py`)
- Game menu → Leaderboard logic: stores player (evidence: `app/main.py`)
- Game menu → Leaderboard logic: stores result (evidence: `app/main.py`)
- Game menu → Leaderboard logic: requests rankings (evidence: `app/main.py`)
- Leaderboard logic → SQLite database: reads and writes (evidence: `utils/leaderboard.py`)
- Game menu → Time formatting: formats times (evidence: `app/main.py`)
