# faulknerpearce/terminal_game architecture

> Architecture diagram of the GitHub repository faulknerpearce/terminal_game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faulknerpearce/terminal_game
- Repository: https://github.com/faulknerpearce/terminal_game

## Overview

##### Project Type and Purpose
- This is a CLI (command-line interface) Python game—a single-process, text-based combat engine.
- Purpose: orchestrate a turn-based fight between a player and a goblin, handling attacks, defense maneuvers, and leveling.

##### File Structure
- Top-level modules:
- game_classes.py – Domain models (Weapon, Character).
- game_data_functions.py – Data helpers (e.g., converters, random attack generator).
- game_functions.py – Core combat logic (attack resolution, block/parry handlers).
- game_levels.py – Level-up logic for weapons/characters.
- main.py – Orchestrates setup, game loop, and I/O.
- No external services or database—pure in-memory objects and console I/O.

##### README Insights
- Two main classes: Weapon and Character, each with clear responsibilities.
- A set of standalone functions for combat flow and output.
- The game loop ties everything together at the end of main.py.

##### Main Components
a. CLI Interface (UI Layer)
- Reads player input (attack choice).
- Prints combat results and status updates.
b. Game Loop (Controller)
- Located in main.py: instantiates characters, iterates turns, terminates on health ≤ 0.
c. Domain Model Layer
- Character Class (attributes: name, health, level, weapon).
- Weapon Class (attributes: damage values, XP, level).
d. Combat Engine (Business Logic)
- game_functions.py: character_combat, block, parry.
- game_data_functions.py: enemy_random_attack, convert_int_to_word.
e. Leveling Subsystem
- game_levels.py: level_up triggers for weapons and characters.
f. Data Flow & Interactions
- UI → Game Loop → Combat Engine → Domain Model → Leveling Subsystem → back to UI.

##### Relationships & Patterns
- Controller-Model separation: main.py orchestrates, domain classes hold state.
- Single Responsibility: each module handles one concern (e.g., data conversion, combat logic).
- No external dependencies—pure functions and classes.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "UI Layer"
        UI["CLI Interface\n(main.py)"]:::ui
    end

    subgraph "Controller"
        GL["Game Loop\n(main.py)"]:::ui
    end

    subgraph "Business Logic"
        CE["Combat Engine\n(game_functions.py)"]:::business
    end

    subgraph "Utility"
        UTIL["Combat Utils\n(game_data_functions.py)"]:::utility
    end

    subgraph "Domain Model Layer"
        DM1["Character Class\n(game_classes.py)"]:::domain
        DM2["Weapon Class\n(game_classes.py)"]:::domain
    end

    subgraph "Leveling Subsystem"
        LS["Leveling Subsystem\n(game_levels.py)"]:::utility
    end

    UI -->|"reads input"| GL
    GL -->|"invoke combat"| CE
    CE -->|"uses domain models"| DM1
    CE -->|"uses domain models"| DM2
    CE -->|"calls utils"| UTIL
    CE -->|"returns XP"| LS
    LS -->|"updates models"| DM1
    LS -->|"updates models"| DM2
    LS -->|"signals next turn"| GL
    GL -->|"outputs results"| UI

    click UI "https://github.com/faulknerpearce/terminal_game/blob/main/main.py"
    click GL "https://github.com/faulknerpearce/terminal_game/blob/main/main.py"
    click DM1 "https://github.com/faulknerpearce/terminal_game/blob/main/game_classes.py"
    click DM2 "https://github.com/faulknerpearce/terminal_game/blob/main/game_classes.py"
    click CE "https://github.com/faulknerpearce/terminal_game/blob/main/game_functions.py"
    click UTIL "https://github.com/faulknerpearce/terminal_game/blob/main/game_data_functions.py"
    click LS "https://github.com/faulknerpearce/terminal_game/blob/main/game_levels.py"

    classDef ui fill:#CFE2F3,stroke:#0366d6,color:#0366d6
    classDef business fill:#D9EAD3,stroke:#38761d,color:#38761d
    classDef domain fill:#FFF2CC,stroke:#b45f06,color:#b45f06
    classDef utility fill:#FCE5CD,stroke:#e69138,color:#e69138
```
