# xrubin/mordheim-gpt architecture

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

- Interactive diagram: https://gitdiagram.com/xrubin/mordheim-gpt
- Repository: https://github.com/xrubin/mordheim-gpt

## Overview

##### Project Type and Purpose
- This is a PHP-based domain simulation library for the tabletop game Mordheim (“Mordheim Classic simulator”).
- It contains pure business logic (battle rules, fighters, warbands, strategies) and no UI or web frontend.

##### File-Structure Analysis
- Top-level:
- `src/` contains all PHP code, organized by sub-packages:
– `Data/Attributes` and other `Data/` classes (data models, attribute definitions)
– `Rule/` (battle rules engine)
– `Strategy/` (Strategy pattern implementations for battle AI)
– `Traits/`, `Exceptions/`, Interfaces, Domain entities (e.g. Fighter, Warband, Battle)
- `examples/` – CLI usage examples (attribute.php, battle.php)
- `tests/` – PHPUnit tests validating each domain class and rule
- `composer.json` – dependency and autoload configuration

##### Key Architectural Patterns
- Domain-Driven Design: Entities (Fighter, Warband, Battle), Value Objects (Characteristics, Spell), Services (EquipmentManager, PathFinder)
- Strategy Pattern (BattleStrategyInterface → AggressiveStrategy, CarefulStrategy, CowardlyStrategy)
- Rule Engine (each rule implements a common interface under `src/Rule`)
- Data Providers / Repositories under `src/Data`
- Use of Interfaces to decouple implementations (e.g. FighterInterface, EquipmentInterface)

##### Main Components
A. Domain Layer
- Entities: Fighter, Warband, Battle, GameField, FieldCell
- Value Objects: Characteristics, Spell, SpecialRule
B. Data Layer
- Data providers / attribute definitions (`src/Data/Attributes/*`)
- EquipmentList, Mutation, SkillGroup
C. Battle Engine Services
- Rule Engine (`src/Rule/*`)
- PathFinder (movement logic)
- EquipmentManager (inventory logic)
- BattleLogger (logging events)
D. Strategy Module
- BattleStrategyInterface + implementations (AggressiveStrategy, etc.)
E. Infrastructure
- Composer Autoload
- PHPUnit Tests (external to runtime, verifies correctness)
- Examples (entry points for CLI simulation)

##### Relationships and Interactions
- Battle orchestrates the simulation:
→ loads Domain Entities (Warband, Fighter) using Data providers
→ uses PathFinder to calculate moves on GameField
→ applies each Rule in the Rule Engine to update FighterState
→ delegates AI decisions to a Strategy implementation
→ emits events to BattleLogger
- EquipmentManager is used by Fighters when modifying equipment.
- Data Attributes repository is read by Domain Entities to initialize stats.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Domain Layer
    subgraph "Domain Layer" 
        direction TB
        Fighter["Fighter"] 
        Warband["Warband"]
        Battle["Battle"]
        GameField["GameField"]
        FieldCell["FieldCell"]
        CharacteristicsVO["Characteristics"] 
        SpellVO["Spell"] 
        SpecialRuleVO["SpecialRule"]
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DataAttributes["Attributes Repository"] 
        EquipmentList["EquipmentList"]
        Equipment["Equipment"]
        Mutation["Mutation"]
        SkillGroup["SkillGroup"]
        WarbandData["Warband Data Model"]
    end

    %% Rule Engine Layer
    subgraph "Rules Layer"
        direction TB
        RuleEngine["Rule Engine"]
        PathFinder["PathFinder"]
        EquipmentManager["EquipmentManager"]
        BattleLogger["BattleLogger"]
    end

    %% Strategy Layer
    subgraph "Strategy Layer"
        direction TB
        BattleStrategyInterface["BattleStrategyInterface"]
        BaseBattleStrategy["BaseBattleStrategy"]
        AggressiveStrategy["AggressiveStrategy"]
        CarefulStrategy["CarefulStrategy"]
        CowardlyStrategy["CowardlyStrategy"]
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        Composer["composer.json"]
        Examples["CLI Examples"]
        Tests["PHPUnit Tests"]
    end

    %% Dependencies and Flows
    Battle -->|"uses"| PathFinder
    Battle -->|"uses"| RuleEngine
    Battle -->|"emits events to"| BattleLogger
    Battle -->|"loads entities from"| DataAttributes
    Fighter -->|"uses"| EquipmentManager

    AggressiveStrategy -->|"implements"| BattleStrategyInterface
    CarefulStrategy -->|"implements"| BattleStrategyInterface
    CowardlyStrategy -->|"implements"| BattleStrategyInterface
    BaseBattleStrategy -->|"implements"| BattleStrategyInterface

    Examples -->|"entry point"| Battle
    Tests -->|"verifies"| Battle

    %% Click Events
    click Fighter "https://github.com/xrubin/mordheim-gpt/blob/master/src/Fighter.php"
    click Warband "https://github.com/xrubin/mordheim-gpt/blob/master/src/Warband.php"
    click Battle "https://github.com/xrubin/mordheim-gpt/blob/master/src/Battle.php"
    click GameField "https://github.com/xrubin/mordheim-gpt/blob/master/src/GameField.php"
    click FieldCell "https://github.com/xrubin/mordheim-gpt/blob/master/src/FieldCell.php"
    click CharacteristicsVO "https://github.com/xrubin/mordheim-gpt/blob/master/src/Characteristics.php"
    click SpellVO "https://github.com/xrubin/mordheim-gpt/blob/master/src/Data/Spell.php"
    click SpellVO "https://github.com/xrubin/mordheim-gpt/blob/master/src/SpellInterface.php"
    click SpecialRuleVO "https://github.com/xrubin/mordheim-gpt/blob/master/src/SpecialRule.php"
    click SpecialRuleVO "https://github.com/xrubin/mordheim-gpt/blob/master/src/SpecialRuleInterface.php"
    click DataAttributes "https://github.com/xrubin/mordheim-gpt/tree/master/src/Data/Attributes/"
    click EquipmentList "https://github.com/xrubin/mordheim-gpt/blob/master/src/Data/EquipmentList.php"
    click Equipment "https://github.com/xrubin/mordheim-gpt/blob/master/src/Data/Equipment.php"
    click Mutation "https://github.com/xrubin/mordheim-gpt/blob/master/src/Data/Mutation.php"
    click SkillGroup "https://github.com/xrubin/mordheim-gpt/blob/master/src/Data/SkillGroup.php"
    click WarbandData "https://github.com/xrubin/mordheim-gpt/blob/master/src/Data/Warband.php"
    click PathFinder "https://github.com/xrubin/mordheim-gpt/blob/master/src/PathFinder.php"
    click EquipmentManager "https://github.com/xrubin/mordheim-gpt/blob/master/src/EquipmentManager.php"
    click BattleLogger "https://github.com/xrubin/mordheim-gpt/blob/master/src/BattleLogger.php"
    click BattleStrategyInterface "https://github.com/xrubin/mordheim-gpt/blob/master/src/BattleStrategyInterface.php"
    click BaseBattleStrategy "https://github.com/xrubin/mordheim-gpt/blob/master/src/Strategy/BaseBattleStrategy.php"
    click AggressiveStrategy "https://github.com/xrubin/mordheim-gpt/blob/master/src/Strategy/AggressiveStrategy.php"
    click CarefulStrategy "https://github.com/xrubin/mordheim-gpt/blob/master/src/Strategy/CarefulStrategy.php"
    click CowardlyStrategy "https://github.com/xrubin/mordheim-gpt/blob/master/src/Strategy/CowardlyStrategy.php"
    click Composer "https://github.com/xrubin/mordheim-gpt/blob/master/composer.json"
    click Examples "https://github.com/xrubin/mordheim-gpt/blob/master/examples/attribute.php"
    click Examples "https://github.com/xrubin/mordheim-gpt/blob/master/examples/battle.php"
    click Tests "https://github.com/xrubin/mordheim-gpt/tree/master/tests/"

    %% Styles
    classDef domain fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef rules fill:#e2d5f7,stroke:#333,stroke-width:1px
    classDef strategy fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef infra fill:#d6d6d6,stroke:#333,stroke-width:1px

    class Fighter,Warband,Battle,GameField,FieldCell,CharacteristicsVO,SpellVO,SpecialRuleVO domain
    class DataAttributes,EquipmentList,Equipment,Mutation,SkillGroup,WarbandData data
    class RuleEngine,PathFinder,EquipmentManager,BattleLogger rules
    class BattleStrategyInterface,BaseBattleStrategy,AggressiveStrategy,CarefulStrategy,CowardlyStrategy strategy
    class Composer,Examples,Tests infra
```
