# jleclanche/fireplace architecture

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

- Interactive diagram: https://gitdiagram.com/jleclanche/fireplace
- Repository: https://github.com/jleclanche/fireplace

## Overview

Fireplace is a Python Hearthstone simulator. Its main workflow is to create a game with two players and decks, set up and advance turns, execute player/card actions, and update game entities and state. Card definitions supply the behaviors that actions execute; selectors and lazy evaluators support those behaviors. The README documents broad card-set coverage. The graph combines sampled runtime relationships with documented capabilities; card-set loading details and some internal dispatch paths were not fully sampled.

Main entry points: [`fireplace/game.py`](https://github.com/jleclanche/fireplace/blob/master/fireplace/game.py) (Game lifecycle), [`fireplace/actions.py`](https://github.com/jleclanche/fireplace/blob/master/fireplace/actions.py) (Game actions), [`fireplace/player.py`](https://github.com/jleclanche/fireplace/blob/master/fireplace/player.py) (Player state), [`fireplace/card.py`](https://github.com/jleclanche/fireplace/blob/master/fireplace/card.py) (Cards and entities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Game Runtime"]
  node_game["Game lifecycle<br/>[game.py]"]
end

subgraph group_domain["Game Domain"]
  node_player["Player state<br/>[player.py]"]
  node_card["Cards and entities<br/>[card.py]"]
  node_entity["Entity base<br/>[entity.py]"]
  node_deck["Deck<br/>[deck.py]"]
  node_enums["Game tags<br/>[enums.py]"]
end

subgraph group_engine["Rules Engine"]
  node_actions["Game actions<br/>[actions.py]"]
  node_managers["State managers<br/>[managers.py]"]
  node_aura["Aura effects<br/>[aura.py]"]
  node_targeting["Targeting rules<br/>[targeting.py]"]
  node_rules["Play rules<br/>[rules.py]"]
  node_dsl_selector["Entity selectors<br/>[selector.py]"]
  node_dsl_lazy["Lazy numbers<br/>[lazynum.py]"]
  node_dsl_eval["Evaluators<br/>[evaluator.py]"]
  node_dsl_random["Random picker<br/>[random_picker.py]"]
end

subgraph group_content["Card Content"]
  node_carddb[("Card database<br/>[__init__.py]")]
  node_card_scripts["Card helpers<br/>[utils.py]"]
  node_card_sets["Card-set definitions"]
  node_brawls["Brawl modes<br/>[__init__.py]"]
end

node_player_actor(("Player"))

node_player_actor -.->|"starts game"| node_game
node_game -->|"sets up"| node_player
node_game -->|"queues actions"| node_actions
node_game -->|"loads cards"| node_carddb
node_game -->|"tracks state"| node_managers
node_game -->|"uses entities"| node_entity
node_player -->|"executes"| node_actions
node_player -->|"owns cards"| node_card
node_player -->|"holds deck"| node_deck
node_player -->|"reads game state"| node_game
node_player -->|"uses managers"| node_managers
node_card -->|"extends"| node_entity
node_card -->|"uses actions"| node_actions
node_card -->|"uses aura effects"| node_aura
node_card -->|"checks targets"| node_targeting
node_actions -->|"acts on entities"| node_entity
node_actions -->|"notifies observers"| node_managers
node_actions -->|"evaluates targets"| node_dsl_selector
node_aura -->|"registers observers"| node_managers
node_dsl_lazy -->|"uses evaluators"| node_dsl_eval
node_dsl_lazy -->|"selects entities"| node_dsl_selector
node_dsl_eval -->|"evaluates selectors"| node_dsl_selector
node_dsl_random -->|"selects candidates"| node_dsl_selector
node_dsl_random -->|"reads cards"| node_carddb
node_carddb -->|"uses game tags"| node_enums
node_card_scripts -->|"defines card behaviors"| node_actions
node_card_scripts -->|"uses aura effects"| node_aura
node_card_scripts -->|"looks up cards"| node_carddb
node_card_sets -.->|"uses shared helpers"| node_card_scripts
node_brawls -->|"uses game runtime"| node_game
node_brawls -->|"uses card database"| node_carddb
node_brawls -->|"selects brawl cards"| node_card_sets
node_rules -->|"uses card helpers"| node_card_scripts

click node_game "https://github.com/jleclanche/fireplace/blob/master/fireplace/game.py"
click node_player "https://github.com/jleclanche/fireplace/blob/master/fireplace/player.py"
click node_card "https://github.com/jleclanche/fireplace/blob/master/fireplace/card.py"
click node_entity "https://github.com/jleclanche/fireplace/blob/master/fireplace/entity.py"
click node_deck "https://github.com/jleclanche/fireplace/blob/master/fireplace/deck.py"
click node_actions "https://github.com/jleclanche/fireplace/blob/master/fireplace/actions.py"
click node_managers "https://github.com/jleclanche/fireplace/blob/master/fireplace/managers.py"
click node_aura "https://github.com/jleclanche/fireplace/blob/master/fireplace/aura.py"
click node_targeting "https://github.com/jleclanche/fireplace/blob/master/fireplace/targeting.py"
click node_rules "https://github.com/jleclanche/fireplace/blob/master/fireplace/rules.py"
click node_dsl_selector "https://github.com/jleclanche/fireplace/blob/master/fireplace/dsl/selector.py"
click node_dsl_lazy "https://github.com/jleclanche/fireplace/blob/master/fireplace/dsl/lazynum.py"
click node_dsl_eval "https://github.com/jleclanche/fireplace/blob/master/fireplace/dsl/evaluator.py"
click node_dsl_random "https://github.com/jleclanche/fireplace/blob/master/fireplace/dsl/random_picker.py"
click node_carddb "https://github.com/jleclanche/fireplace/blob/master/fireplace/cards/__init__.py"
click node_card_scripts "https://github.com/jleclanche/fireplace/blob/master/fireplace/cards/utils.py"
click node_card_sets "https://github.com/jleclanche/fireplace/tree/master/fireplace/cards"
click node_brawls "https://github.com/jleclanche/fireplace/blob/master/fireplace/brawls/__init__.py"
click node_enums "https://github.com/jleclanche/fireplace/blob/master/fireplace/enums.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_game toneBlue
class node_player,node_card,node_entity,node_deck,node_enums toneAmber
class node_actions,node_managers,node_aura,node_targeting,node_rules,node_dsl_selector,node_dsl_lazy,node_dsl_eval,node_dsl_random toneMint
class node_carddb,node_card_scripts,node_card_sets,node_brawls toneRose
class node_player_actor toneIndigo
```

## Components

### Game Runtime

- [Game lifecycle](https://github.com/jleclanche/fireplace/blob/master/fireplace/game.py): `fireplace/game.py`

### Game Domain

- [Player state](https://github.com/jleclanche/fireplace/blob/master/fireplace/player.py): `fireplace/player.py`
- [Cards and entities](https://github.com/jleclanche/fireplace/blob/master/fireplace/card.py): `fireplace/card.py`
- [Entity base](https://github.com/jleclanche/fireplace/blob/master/fireplace/entity.py): `fireplace/entity.py`
- [Deck](https://github.com/jleclanche/fireplace/blob/master/fireplace/deck.py): `fireplace/deck.py`
- [Game tags](https://github.com/jleclanche/fireplace/blob/master/fireplace/enums.py): `fireplace/enums.py`

### Rules Engine

- [Game actions](https://github.com/jleclanche/fireplace/blob/master/fireplace/actions.py): `fireplace/actions.py`
- [State managers](https://github.com/jleclanche/fireplace/blob/master/fireplace/managers.py): `fireplace/managers.py`
- [Aura effects](https://github.com/jleclanche/fireplace/blob/master/fireplace/aura.py): `fireplace/aura.py`
- [Targeting rules](https://github.com/jleclanche/fireplace/blob/master/fireplace/targeting.py): `fireplace/targeting.py`
- [Play rules](https://github.com/jleclanche/fireplace/blob/master/fireplace/rules.py): `fireplace/rules.py`
- [Entity selectors](https://github.com/jleclanche/fireplace/blob/master/fireplace/dsl/selector.py): `fireplace/dsl/selector.py`
- [Lazy numbers](https://github.com/jleclanche/fireplace/blob/master/fireplace/dsl/lazynum.py): `fireplace/dsl/lazynum.py`
- [Evaluators](https://github.com/jleclanche/fireplace/blob/master/fireplace/dsl/evaluator.py): `fireplace/dsl/evaluator.py`
- [Random picker](https://github.com/jleclanche/fireplace/blob/master/fireplace/dsl/random_picker.py): `fireplace/dsl/random_picker.py`

### Card Content

- [Card database](https://github.com/jleclanche/fireplace/blob/master/fireplace/cards/__init__.py): `fireplace/cards/__init__.py`
- [Card helpers](https://github.com/jleclanche/fireplace/blob/master/fireplace/cards/utils.py): `fireplace/cards/utils.py`
- [Card-set definitions](https://github.com/jleclanche/fireplace/tree/master/fireplace/cards): `fireplace/cards`
- [Brawl modes](https://github.com/jleclanche/fireplace/blob/master/fireplace/brawls/__init__.py): `fireplace/brawls/__init__.py`

### Other components

- **Player**

## Connections

- Player → Game lifecycle: starts game
- Game lifecycle → Player state: sets up (evidence: `fireplace/game.py`)
- Game lifecycle → Game actions: queues actions (evidence: `fireplace/game.py`)
- Game lifecycle → Card database: loads cards (evidence: `fireplace/game.py`)
- Game lifecycle → State managers: tracks state (evidence: `fireplace/game.py`)
- Game lifecycle → Entity base: uses entities (evidence: `fireplace/game.py`)
- Player state → Game actions: executes (evidence: `fireplace/player.py`)
- Player state → Cards and entities: owns cards (evidence: `fireplace/player.py`)
- Player state → Deck: holds deck (evidence: `fireplace/player.py`)
- Player state → Game lifecycle: reads game state (evidence: `fireplace/player.py`)
- Player state → State managers: uses managers (evidence: `fireplace/player.py`)
- Cards and entities → Entity base: extends (evidence: `fireplace/card.py`)
- Cards and entities → Game actions: uses actions (evidence: `fireplace/card.py`)
- Cards and entities → Aura effects: uses aura effects (evidence: `fireplace/card.py`)
- Cards and entities → Targeting rules: checks targets (evidence: `fireplace/card.py`)
- Game actions → Entity base: acts on entities (evidence: `fireplace/actions.py`)
- Game actions → State managers: notifies observers (evidence: `fireplace/actions.py`)
- Game actions → Entity selectors: evaluates targets (evidence: `fireplace/actions.py`)
- Aura effects → State managers: registers observers (evidence: `fireplace/aura.py`)
- Lazy numbers → Evaluators: uses evaluators (evidence: `fireplace/dsl/lazynum.py`)
- Lazy numbers → Entity selectors: selects entities (evidence: `fireplace/dsl/lazynum.py`)
- Evaluators → Entity selectors: evaluates selectors (evidence: `fireplace/dsl/evaluator.py`)
- Random picker → Entity selectors: selects candidates (evidence: `fireplace/dsl/random_picker.py`)
- Random picker → Card database: reads cards (evidence: `fireplace/dsl/random_picker.py`)
- Card database → Game tags: uses game tags (evidence: `fireplace/cards/__init__.py`)
- Card helpers → Game actions: defines card behaviors (evidence: `fireplace/cards/utils.py`)
- Card helpers → Aura effects: uses aura effects (evidence: `fireplace/cards/utils.py`)
- Card helpers → Card database: looks up cards (evidence: `fireplace/cards/utils.py`)
- Card-set definitions → Card helpers: uses shared helpers (evidence: `fireplace/cards/blackrock/adventure.py`)
- Brawl modes → Game lifecycle: uses game runtime (evidence: `fireplace/brawls/__init__.py`)
- Brawl modes → Card database: uses card database (evidence: `fireplace/brawls/__init__.py`)
- Brawl modes → Card-set definitions: selects brawl cards (evidence: `fireplace/brawls/__init__.py`)
- Play rules → Card helpers: uses card helpers (evidence: `fireplace/rules.py`)
