# itsvqt/liars-dice architecture

> Architecture diagram of the GitHub repository itsvqt/liars-dice, 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/itsvqt/liars-dice
- Repository: https://github.com/itsvqt/liars-dice

## Overview

This is a terminal Liar’s Dice game for one human and configurable AI opponents. The main workflow is setup, dice rolls, rotating bids and challenges, rule-based resolution, player elimination, and winner display. The graph preserves the distinct game, turn-order, rules, player/AI, and terminal-UI responsibilities. Relationships are based on excerpts, the SOURCE INDEX, and README; unsampled implementation details are not inferred.

Main entry points: [`source/engine/game.py`](https://github.com/itsvqt/liars-dice/blob/main/source/engine/game.py) (Game loop), [`source/models/player/base/player.py`](https://github.com/itsvqt/liars-dice/blob/main/source/models/player/base/player.py) (Player state), [`source/ui/terminal.py`](https://github.com/itsvqt/liars-dice/blob/main/source/ui/terminal.py) (Terminal UI), [`source/engine/player_circle.py`](https://github.com/itsvqt/liars-dice/blob/main/source/engine/player_circle.py) (Turn circle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Game entry"]
  node_main["Game launcher<br/>[main.py]"]
end

subgraph group_gameplay["Game orchestration"]
  node_game["Game loop<br/>[game.py]"]
  node_rules["Game rules<br/>[rules.py]"]
  node_circle["Turn circle<br/>[player_circle.py]"]
  node_constants["Game settings<br/>[constants.py]"]
  node_typeparse["Input parsing<br/>[type_parsing.py]"]
end

subgraph group_players["Players and turns"]
  node_player["Player state<br/>[player.py]"]
  node_human["Human player<br/>[human_player.py]"]
  node_ai["Bot strategy<br/>[ai_player.py]"]
end

subgraph group_interface["Terminal interface"]
  node_ui["UI contract<br/>[ui.py]"]
  node_terminal["Terminal UI<br/>[terminal.py]"]
end

subgraph group_models["Game models"]
  node_dice["Die model<br/>[dice.py]"]
  node_bid["Bid model<br/>[bid.py]"]
end

node_human_actor(("Human player"))

node_main -->|"creates"| node_terminal
node_main -->|"starts"| node_game
node_game -->|"requests and reports"| node_ui
node_terminal -->|"implements"| node_ui
node_human_actor -->|"provides choices"| node_terminal
node_game -->|"reads settings"| node_constants
node_game -->|"manages turns"| node_circle
node_game -->|"checks outcomes"| node_rules
node_game -->|"creates and queries"| node_ai
node_game -->|"creates"| node_human
node_game -->|"validates bids"| node_bid
node_ai -->|"constructs bids"| node_bid
node_rules -->|"compares bids"| node_bid
node_rules -->|"checks game end"| node_circle
node_circle -->|"rotates players"| node_player
node_circle -->|"checks player limits"| node_constants
node_player -->|"rolls dice"| node_dice
node_player -->|"sets hand size"| node_constants
node_human -->|"inherits state"| node_player
node_ai -->|"uses player state"| node_player
node_terminal -->|"displays bids"| node_bid
node_terminal -->|"displays player state"| node_player

click node_main "https://github.com/itsvqt/liars-dice/blob/main/source/main.py"
click node_game "https://github.com/itsvqt/liars-dice/blob/main/source/engine/game.py"
click node_rules "https://github.com/itsvqt/liars-dice/blob/main/source/engine/rules.py"
click node_circle "https://github.com/itsvqt/liars-dice/blob/main/source/engine/player_circle.py"
click node_constants "https://github.com/itsvqt/liars-dice/blob/main/source/utility/constants.py"
click node_typeparse "https://github.com/itsvqt/liars-dice/blob/main/source/utility/type_parsing.py"
click node_player "https://github.com/itsvqt/liars-dice/blob/main/source/models/player/base/player.py"
click node_human "https://github.com/itsvqt/liars-dice/blob/main/source/models/player/human_player.py"
click node_ai "https://github.com/itsvqt/liars-dice/blob/main/source/models/player/ai_player.py"
click node_dice "https://github.com/itsvqt/liars-dice/blob/main/source/models/dice.py"
click node_bid "https://github.com/itsvqt/liars-dice/blob/main/source/models/bid.py"
click node_ui "https://github.com/itsvqt/liars-dice/blob/main/source/ui/base/ui.py"
click node_terminal "https://github.com/itsvqt/liars-dice/blob/main/source/ui/terminal.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_main toneBlue
class node_game,node_rules,node_circle,node_constants,node_typeparse toneAmber
class node_player,node_human,node_ai toneMint
class node_ui,node_terminal toneRose
class node_dice,node_bid,node_human_actor toneIndigo
```

## Components

### Game entry

- [Game launcher](https://github.com/itsvqt/liars-dice/blob/main/source/main.py): `source/main.py`

### Game orchestration

- [Game loop](https://github.com/itsvqt/liars-dice/blob/main/source/engine/game.py): `source/engine/game.py`
- [Game rules](https://github.com/itsvqt/liars-dice/blob/main/source/engine/rules.py): `source/engine/rules.py`
- [Turn circle](https://github.com/itsvqt/liars-dice/blob/main/source/engine/player_circle.py): `source/engine/player_circle.py`
- [Game settings](https://github.com/itsvqt/liars-dice/blob/main/source/utility/constants.py): `source/utility/constants.py`
- [Input parsing](https://github.com/itsvqt/liars-dice/blob/main/source/utility/type_parsing.py): `source/utility/type_parsing.py`

### Players and turns

- [Player state](https://github.com/itsvqt/liars-dice/blob/main/source/models/player/base/player.py): `source/models/player/base/player.py`
- [Human player](https://github.com/itsvqt/liars-dice/blob/main/source/models/player/human_player.py): `source/models/player/human_player.py`
- [Bot strategy](https://github.com/itsvqt/liars-dice/blob/main/source/models/player/ai_player.py): `source/models/player/ai_player.py`

### Terminal interface

- [UI contract](https://github.com/itsvqt/liars-dice/blob/main/source/ui/base/ui.py): `source/ui/base/ui.py`
- [Terminal UI](https://github.com/itsvqt/liars-dice/blob/main/source/ui/terminal.py): `source/ui/terminal.py`

### Game models

- [Die model](https://github.com/itsvqt/liars-dice/blob/main/source/models/dice.py): `source/models/dice.py`
- [Bid model](https://github.com/itsvqt/liars-dice/blob/main/source/models/bid.py): `source/models/bid.py`

### Other components

- **Human player**

## Connections

- Game launcher → Terminal UI: creates (evidence: `source/main.py`)
- Game launcher → Game loop: starts (evidence: `source/main.py`)
- Game loop → UI contract: requests and reports (evidence: `source/engine/game.py`)
- Terminal UI → UI contract: implements (evidence: `source/ui/terminal.py`)
- Human player → Terminal UI: provides choices (evidence: `source/ui/terminal.py`)
- Game loop → Game settings: reads settings (evidence: `source/engine/game.py`)
- Game loop → Turn circle: manages turns (evidence: `source/engine/game.py`)
- Game loop → Game rules: checks outcomes (evidence: `source/engine/game.py`)
- Game loop → Bot strategy: creates and queries (evidence: `source/engine/game.py`)
- Game loop → Human player: creates (evidence: `source/engine/game.py`)
- Game loop → Bid model: validates bids (evidence: `source/engine/game.py`)
- Bot strategy → Bid model: constructs bids (evidence: `source/models/player/ai_player.py`)
- Game rules → Bid model: compares bids (evidence: `source/engine/rules.py`)
- Game rules → Turn circle: checks game end (evidence: `source/engine/rules.py`)
- Turn circle → Player state: rotates players (evidence: `source/engine/player_circle.py`)
- Turn circle → Game settings: checks player limits (evidence: `source/engine/player_circle.py`)
- Player state → Die model: rolls dice (evidence: `source/models/player/base/player.py`)
- Player state → Game settings: sets hand size (evidence: `source/models/player/base/player.py`)
- Human player → Player state: inherits state (evidence: `source/models/player/human_player.py`)
- Bot strategy → Player state: uses player state (evidence: `source/models/player/ai_player.py`)
- Terminal UI → Bid model: displays bids (evidence: `source/ui/terminal.py`)
- Terminal UI → Player state: displays player state (evidence: `source/ui/terminal.py`)
