# demonhero93/dndbalancer architecture

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

- Interactive diagram: https://gitdiagram.com/demonhero93/dndbalancer
- Repository: https://github.com/demonhero93/dndbalancer

## Overview

This is a D&D 5e combat-simulation package. The principal workflow begins in `main.py`, which delegates into the package and combat engine; combatants’ actions resolve attacks and apply rules to update combat state. The package also covers character/class features, spells, and monster-data parsing. Edges reflect imports and calls shown in the supplied excerpts or SOURCE INDEX; unsampled subsystems are represented where their paths are supported, but their internal wiring is not inferred.

Main entry points: [`dnd_sim/engine/combat/attack.py`](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/engine/combat/attack.py) (Attack resolver), [`dnd_sim/engine/combat/encounter.py`](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/engine/combat/encounter.py) (Encounter loop), [`main.py`](https://github.com/demonhero93/dndbalancer/blob/main/main.py) (Application entry), [`dnd_sim/__init__.py`](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/__init__.py) (Public package API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and reporting"]
  node_main["Application entry<br/>[main.py]"]
  node_stats["Combat statistics<br/>[stats.py]"]
end

subgraph group_domain["Characters and actions"]
  node_package["Public package API<br/>[__init__.py]"]
  node_combatant["Combatant model<br/>[combatant.py]"]
  node_actions["Action model<br/>[actions.py]"]
  node_attackmodel["Attack definition<br/>[attack.py]"]
end

subgraph group_engine["Combat resolution"]
  node_encounter["Encounter loop<br/>[encounter.py]"]
  node_attackengine["Attack resolver<br/>[attack.py]"]
  node_targeting["Target selection<br/>[targeting.py]"]
  node_dice["Dice and randomness<br/>[dice.py]"]
end

subgraph group_rules["Rules and features"]
  node_conditions["Condition state<br/>[conditions.py]"]
  node_damage["Damage rules<br/>[damage.py]"]
  node_saves["Saving throws<br/>[saves.py]"]
  node_modifiers["Roll modifiers<br/>[roll_modifiers.py]"]
  node_traits["Monster traits<br/>[__init__.py]"]
  node_spells["Spell rules<br/>[actions.py]"]
  node_classfeatures["Class features<br/>[features.py]"]
end

subgraph group_data["Monster data"]
  node_dataapi["D&amp;D API client<br/>[api_client.py]"]
  node_parsers["Monster parsers"]
end

node_user(("Simulator user"))

node_user -->|"runs"| node_main
node_main -->|"imports API"| node_package
node_main -->|"uses statistics"| node_stats
node_main -->|"uses features"| node_classfeatures
node_package -->|"exports model"| node_combatant
node_package -->|"exports actions"| node_actions
node_package -->|"exports attacks"| node_attackmodel
node_combatant -->|"builds actions"| node_actions
node_actions -->|"dispatches attack"| node_attackengine
node_encounter -->|"executes actions"| node_actions
node_encounter -->|"selects targets"| node_targeting
node_attackengine -->|"resolves attack"| node_attackmodel
node_attackengine -->|"updates combatants"| node_combatant
node_attackengine -->|"checks conditions"| node_conditions
node_attackengine -->|"applies damage"| node_damage
node_attackengine -->|"gets modifiers"| node_modifiers
node_attackengine -->|"resolves saves"| node_saves
node_encounter -->|"advances conditions"| node_conditions
node_encounter -->|"applies effects"| node_damage
node_encounter -->|"dispatches traits"| node_traits
node_encounter -->|"uses randomness"| node_dice
node_spells -->|"applies conditions"| node_conditions
node_spells -->|"applies damage"| node_damage
node_spells -->|"selects targets"| node_targeting
node_parsers -->|"builds conditions"| node_conditions
node_parsers -->|"builds saves"| node_saves
node_dataapi -.-> node_parsers

click node_main "https://github.com/demonhero93/dndbalancer/blob/main/main.py"
click node_stats "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/engine/stats.py"
click node_package "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/__init__.py"
click node_combatant "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/model/combatant.py"
click node_actions "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/model/actions.py"
click node_attackmodel "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/model/attack.py"
click node_encounter "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/engine/combat/encounter.py"
click node_attackengine "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/engine/combat/attack.py"
click node_targeting "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/core/targeting.py"
click node_dice "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/core/dice.py"
click node_conditions "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/conditions.py"
click node_damage "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/damage.py"
click node_saves "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/saves.py"
click node_modifiers "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/roll_modifiers.py"
click node_traits "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/traits/__init__.py"
click node_spells "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/spells/actions.py"
click node_classfeatures "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/classes/barbarian/features.py"
click node_dataapi "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/data/api_client.py"
click node_parsers "https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/data/condition_parser.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,node_stats,node_user toneBlue
class node_package,node_combatant,node_actions,node_attackmodel toneAmber
class node_encounter,node_attackengine,node_targeting,node_dice toneMint
class node_conditions,node_damage,node_saves,node_modifiers,node_traits,node_spells,node_classfeatures toneRose
class node_dataapi,node_parsers toneIndigo
```

## Components

### Entry and reporting

- [Application entry](https://github.com/demonhero93/dndbalancer/blob/main/main.py): `main.py`
- [Combat statistics](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/engine/stats.py): `dnd_sim/engine/stats.py`

### Characters and actions

- [Public package API](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/__init__.py): `dnd_sim/__init__.py`
- [Combatant model](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/model/combatant.py): `dnd_sim/model/combatant.py`
- [Action model](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/model/actions.py): `dnd_sim/model/actions.py`
- [Attack definition](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/model/attack.py): `dnd_sim/model/attack.py`

### Combat resolution

- [Encounter loop](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/engine/combat/encounter.py): `dnd_sim/engine/combat/encounter.py`
- [Attack resolver](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/engine/combat/attack.py): `dnd_sim/engine/combat/attack.py`
- [Target selection](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/core/targeting.py): `dnd_sim/core/targeting.py`
- [Dice and randomness](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/core/dice.py): `dnd_sim/core/dice.py`

### Rules and features

- [Condition state](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/conditions.py): `dnd_sim/rules/conditions.py`
- [Damage rules](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/damage.py): `dnd_sim/rules/damage.py`
- [Saving throws](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/saves.py): `dnd_sim/rules/saves.py`
- [Roll modifiers](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/roll_modifiers.py): `dnd_sim/rules/roll_modifiers.py`
- [Monster traits](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/traits/__init__.py): `dnd_sim/rules/traits/__init__.py`
- [Spell rules](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/spells/actions.py): `dnd_sim/rules/spells/actions.py`
- [Class features](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/rules/classes/barbarian/features.py): `dnd_sim/rules/classes/barbarian/features.py`

### Monster data

- [D&D API client](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/data/api_client.py): `dnd_sim/data/api_client.py`
- [Monster parsers](https://github.com/demonhero93/dndbalancer/blob/main/dnd_sim/data/condition_parser.py): `dnd_sim/data/condition_parser.py`

### Other components

- **Simulator user**

## Connections

- Simulator user → Application entry: runs (evidence: `main.py`)
- Application entry → Public package API: imports API (evidence: `main.py`)
- Application entry → Combat statistics: uses statistics (evidence: `main.py`)
- Application entry → Class features: uses features (evidence: `main.py`)
- Public package API → Combatant model: exports model (evidence: `dnd_sim/__init__.py`)
- Public package API → Action model: exports actions (evidence: `dnd_sim/__init__.py`)
- Public package API → Attack definition: exports attacks (evidence: `dnd_sim/__init__.py`)
- Combatant model → Action model: builds actions (evidence: `dnd_sim/model/combatant.py`)
- Action model → Attack resolver: dispatches attack (evidence: `dnd_sim/model/actions.py`)
- Encounter loop → Action model: executes actions (evidence: `dnd_sim/engine/combat/encounter.py`)
- Encounter loop → Target selection: selects targets (evidence: `dnd_sim/engine/combat/encounter.py`)
- Attack resolver → Attack definition: resolves attack (evidence: `dnd_sim/engine/combat/attack.py`)
- Attack resolver → Combatant model: updates combatants (evidence: `dnd_sim/engine/combat/attack.py`)
- Attack resolver → Condition state: checks conditions (evidence: `dnd_sim/engine/combat/attack.py`)
- Attack resolver → Damage rules: applies damage (evidence: `dnd_sim/engine/combat/attack.py`)
- Attack resolver → Roll modifiers: gets modifiers (evidence: `dnd_sim/engine/combat/attack.py`)
- Attack resolver → Saving throws: resolves saves (evidence: `dnd_sim/engine/combat/attack.py`)
- Encounter loop → Condition state: advances conditions (evidence: `dnd_sim/engine/combat/encounter.py`)
- Encounter loop → Damage rules: applies effects (evidence: `dnd_sim/engine/combat/encounter.py`)
- Encounter loop → Monster traits: dispatches traits (evidence: `dnd_sim/engine/combat/encounter.py`)
- Encounter loop → Dice and randomness: uses randomness (evidence: `dnd_sim/engine/combat/encounter.py`)
- Spell rules → Condition state: applies conditions (evidence: `dnd_sim/rules/spells/actions.py`)
- Spell rules → Damage rules: applies damage (evidence: `dnd_sim/rules/spells/actions.py`)
- Spell rules → Target selection: selects targets (evidence: `dnd_sim/rules/spells/actions.py`)
- Monster parsers → Condition state: builds conditions (evidence: `dnd_sim/data/condition_parser.py`)
- Monster parsers → Saving throws: builds saves (evidence: `dnd_sim/data/condition_parser.py`)
- D&D API client → Monster parsers