# herdisheida/wordlepuzzle architecture

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

- Interactive diagram: https://gitdiagram.com/herdisheida/wordlepuzzle
- Repository: https://github.com/herdisheida/wordlepuzzle

## Overview

This is a terminal Wordle game. A player enters through the menu, configures a series, receives a random word of the chosen length, submits guesses for validation and feedback, and sees results; the series is then saved to per-user JSON history. The menu also supports adding words and browsing history and statistics. Edges reflect calls visible in excerpts or documented behavior; the word-bank file path in source differs in case from the tree, so storage is represented by its enclosing directory.

Main entry points: [`ui_layer/GameMenu.py`](https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/GameMenu.py) (Game menu), [`ui_layer/GameUI.py`](https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/GameUI.py) (Round interface), [`ui_layer/GameHistoryUI.py`](https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/GameHistoryUI.py) (History interface), [`logic_layer/WordleGame.py`](https://github.com/herdisheida/wordlepuzzle/blob/main/logic_layer/WordleGame.py) (Wordle round)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entryplay["Menu and play"]
  node_launcher["Program entry<br/>[start.py]"]
  node_menu["Game menu<br/>[GameMenu.py]"]
  node_gameui["Round interface<br/>[GameUI.py]"]
end

subgraph group_gamelogic["Game logic"]
  node_game["Wordle round<br/>[WordleGame.py]"]
  node_guess["Guess record<br/>[Guess.py]"]
  node_series["Game series<br/>[GameSeries.py]"]
end

subgraph group_persistence["Word and history storage"]
  node_wordbank["Word bank<br/>[WordBank.py]"]
  node_wordbankfiles[("Word-bank files")]
  node_history["History storage"]
  node_results[("User result files")]
end

subgraph group_historyui["History and presentation"]
  node_historyui["History interface<br/>[GameHistoryUI.py]"]
  node_color["Terminal formatting<br/>[ColorText.py]"]
end

node_player(("Player"))

node_player -->|"starts"| node_launcher
node_launcher -->|"runs"| node_menu
node_player -->|"chooses options"| node_menu
node_menu -->|"selects word"| node_wordbank
node_menu -->|"creates series"| node_series
node_menu -->|"creates round"| node_game
node_menu -->|"starts round"| node_gameui
node_gameui -->|"reads guesses"| node_player
node_gameui -->|"submits guesses"| node_game
node_game -->|"records guesses"| node_guess
node_gameui -->|"adds completed game"| node_series
node_menu -->|"opens history"| node_historyui
node_menu -->|"saves series"| node_historyui
node_historyui -->|"loads and saves"| node_history
node_history -->|"reads and writes"| node_results
node_wordbank -.->|"reads and updates"| node_wordbankfiles
node_gameui -->|"formats feedback"| node_color
node_historyui -->|"formats history"| node_color

click node_launcher "https://github.com/herdisheida/wordlepuzzle/blob/main/start.py"
click node_menu "https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/GameMenu.py"
click node_gameui "https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/GameUI.py"
click node_game "https://github.com/herdisheida/wordlepuzzle/blob/main/logic_layer/WordleGame.py"
click node_guess "https://github.com/herdisheida/wordlepuzzle/blob/main/logic_layer/Guess.py"
click node_series "https://github.com/herdisheida/wordlepuzzle/blob/main/logic_layer/GameSeries.py"
click node_wordbank "https://github.com/herdisheida/wordlepuzzle/blob/main/storage_layer/wordbank/WordBank.py"
click node_wordbankfiles "https://github.com/herdisheida/wordlepuzzle/tree/main/storage_layer/wordbank"
click node_historyui "https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/GameHistoryUI.py"
click node_history "https://github.com/herdisheida/wordlepuzzle/blob/main/storage_layer/GameHistory_storage.py"
click node_results "https://github.com/herdisheida/wordlepuzzle/tree/main/storage_layer/results"
click node_color "https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/ColorText.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_launcher,node_menu,node_gameui toneBlue
class node_game,node_guess,node_series toneAmber
class node_wordbank,node_wordbankfiles,node_history,node_results toneMint
class node_historyui,node_color toneRose
class node_player toneIndigo
```

## Components

### Menu and play

- [Program entry](https://github.com/herdisheida/wordlepuzzle/blob/main/start.py): `start.py`
- [Game menu](https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/GameMenu.py): `ui_layer/GameMenu.py`
- [Round interface](https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/GameUI.py): `ui_layer/GameUI.py`

### Game logic

- [Wordle round](https://github.com/herdisheida/wordlepuzzle/blob/main/logic_layer/WordleGame.py): `logic_layer/WordleGame.py`
- [Guess record](https://github.com/herdisheida/wordlepuzzle/blob/main/logic_layer/Guess.py): `logic_layer/Guess.py`
- [Game series](https://github.com/herdisheida/wordlepuzzle/blob/main/logic_layer/GameSeries.py): `logic_layer/GameSeries.py`

### Word and history storage

- [Word bank](https://github.com/herdisheida/wordlepuzzle/blob/main/storage_layer/wordbank/WordBank.py): `storage_layer/wordbank/WordBank.py`
- [Word-bank files](https://github.com/herdisheida/wordlepuzzle/tree/main/storage_layer/wordbank): `storage_layer/wordbank`
- [History storage](https://github.com/herdisheida/wordlepuzzle/blob/main/storage_layer/GameHistory_storage.py): `storage_layer/GameHistory_storage.py`
- [User result files](https://github.com/herdisheida/wordlepuzzle/tree/main/storage_layer/results): `storage_layer/results`

### History and presentation

- [History interface](https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/GameHistoryUI.py): `ui_layer/GameHistoryUI.py`
- [Terminal formatting](https://github.com/herdisheida/wordlepuzzle/blob/main/ui_layer/ColorText.py): `ui_layer/ColorText.py`

### Other components

- **Player**

## Connections

- Player → Program entry: starts (evidence: `README.md`)
- Program entry → Game menu: runs (evidence: `start.py`)
- Player → Game menu: chooses options (evidence: `ui_layer/GameMenu.py`)
- Game menu → Word bank: selects word (evidence: `ui_layer/GameMenu.py`)
- Game menu → Game series: creates series (evidence: `ui_layer/GameMenu.py`)
- Game menu → Wordle round: creates round (evidence: `ui_layer/GameMenu.py`)
- Game menu → Round interface: starts round (evidence: `ui_layer/GameMenu.py`)
- Round interface → Player: reads guesses (evidence: `ui_layer/GameUI.py`)
- Round interface → Wordle round: submits guesses (evidence: `ui_layer/GameUI.py`)
- Wordle round → Guess record: records guesses (evidence: `logic_layer/WordleGame.py`)
- Round interface → Game series: adds completed game (evidence: `ui_layer/GameUI.py`)
- Game menu → History interface: opens history (evidence: `ui_layer/GameMenu.py`)
- Game menu → History interface: saves series (evidence: `ui_layer/GameMenu.py`)
- History interface → History storage: loads and saves (evidence: `ui_layer/GameHistoryUI.py`)
- History storage → User result files: reads and writes (evidence: `storage_layer/GameHistory_storage.py`)
- Word bank → Word-bank files: reads and updates
- Round interface → Terminal formatting: formats feedback (evidence: `ui_layer/GameUI.py`)
- History interface → Terminal formatting: formats history (evidence: `ui_layer/GameHistoryUI.py`)