# radar/mtg architecture

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

- Interactive diagram: https://gitdiagram.com/radar/mtg
- Repository: https://github.com/radar/mtg

## Overview

##### Main Components
- Card Definition & DSL
– `CardBuilder` DSL (lib/magic/card_builder.rb)
– Card modules under `lib/magic/cards/*`
- Core Domain Model
– Entities: `Card`, `Permanent`, `Player`, `Game`, `Stack`, `Zone`, `Event`
– Value objects: `Mana`, `Cost`, `Counter`, `Filter`, `Target`
- Engine & Runtime
– `Game` loop and phases (`lib/magic/game/*.rb`)
– Action handlers (`lib/magic/actions/*`)
– Stack processor (`lib/magic/stack/*`)
– Effect resolver (`lib/magic/effects/*`)
– Event broadcaster and listeners (`lib/magic/events/*`)
– Static & replacement abilities (`lib/magic/abilities/*`, `lib/magic/static_ability.rb`)
- Supporting Infrastructure
– Configuration & entrypoints: `bin/console`, `bin/setup`, `Rakefile`
– Test harness: RSpec suite under `spec/`
– Gem metadata: `magic.gemspec`, Bundler files (`Gemfile`, `.tool-versions`)

##### Relationships & Data Flows
- Card Registration Flow
[Card Definitions] → (via DSL) → [Card Registry]
- Game Initialization
[Player modules] + [Card Registry] → instantiate → [Game State]
- Turn & Phase Loop
[Game Engine] triggers → [Phase Handlers] → [Action Prompts]
Player invokes → [Action objects] → pushed onto → [Stack]
- Stack Resolution
[Stack] pops → [Effect Resolver] applies → modifies → [Game State]
Emitted → [Event Bus] → triggers → [Triggered Abilities] / [Replacement Effects]
- Continuous Effects
Monitored by → [Static Ability Manager] → adjusts attributes on → [Permanents]

##### Architectural Patterns
- Domain-Driven Design – clear separation of domain entities (cards, players, zones) vs. engine logic
- Event-Driven – game state changes emit events consumed by triggered abilities and replacement effects
- Strategy & Polymorphism – abilities, costs, effects, event handlers implemented as interchangeable classes/modules
- DSL Extension Points – adding new cards boils down to new Ruby files under `lib/magic/cards`

##### Technologies & Frameworks
- Ruby 3.x – core language
- Bundler & Gem – project packaging (`Gemfile`, `magic.gemspec`)
- RSpec – automated testing (`spec/` directory)
- Rake – build & test tasks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% DSL & Card Definitions
    subgraph "DSL & Card Definitions"
        CB["CardBuilder DSL"]:::extension
        CD["Card Definitions"]:::extension
        CR1["Card List"]:::extension
        CR2["Cards Module"]:::extension
    end

    %% Domain Entities
    subgraph "Domain Entities"
        Card["Card"]:::domain
        Permanent["Permanent"]:::domain
        Player["Player"]:::domain
        Game["Game"]:::domain
        Turn["Turn"]:::domain
        CombatPhase["Combat Phase"]:::domain
        StackEntity["Stack"]:::domain
        Zone["Zones"]:::domain
        EventBase["Event Base & Listeners"]:::domain
        Mana["Mana"]:::domain
        Cost["Cost"]:::domain
        Counter["Counter"]:::domain
        Filter["Filter"]:::domain
        Target["Target"]:::domain
    end

    %% Engine & Runtime
    subgraph "Engine & Runtime"
        Actions["Action Handlers"]:::engine
        StackProc["Stack Processor"]:::engine
        EffectRes["Effect Resolver"]:::engine
        EventBus["Event Bus / Broadcaster"]:::engine
        StaticMgr["Static Ability Manager"]:::engine
        Replacement["Replacement Effects"]:::engine
        Triggered["Triggered Abilities"]:::engine
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        CLI["CLI & Setup Scripts"]:::tooling
        Rake["Rake Tasks"]:::tooling
        Pack["Gem Packaging"]:::tooling
        Test["RSpec Suite"]:::tooling
    end

    %% Relationships & Flows
    CD -->|"registers via DSL"| CR1
    CD -->|"registers via DSL"| CR2
    CR1 -->|used by| Game
    CR2 -->|used by| Game
    Player -->|participates in| Game
    Game -->|drives| Turn
    Turn -->|includes| CombatPhase
    Game -->|manages| StackEntity
    StackEntity -->|processed by| EffectRes
    EffectRes -->|modifies| Game
    Game -->|emits events to| EventBus
    EventBus -->|triggers| Triggered
    EventBus -->|applies| Replacement
    StaticMgr -->|adjusts attributes on| Permanent

    %% Click Events
    click CB "https://github.com/radar/mtg/blob/master/lib/magic/card_builder.rb"
    click CD "https://github.com/radar/mtg/tree/master/lib/magic/cards/"
    click CR1 "https://github.com/radar/mtg/blob/master/lib/magic/card_list.rb"
    click CR2 "https://github.com/radar/mtg/blob/master/lib/magic/cards.rb"
    click Card "https://github.com/radar/mtg/blob/master/lib/magic/card.rb"
    click Permanent "https://github.com/radar/mtg/blob/master/lib/magic/permanent.rb"
    click Player "https://github.com/radar/mtg/blob/master/lib/magic/player.rb"
    click Game "https://github.com/radar/mtg/blob/master/lib/magic/game.rb"
    click Turn "https://github.com/radar/mtg/blob/master/lib/magic/game/turn.rb"
    click CombatPhase "https://github.com/radar/mtg/blob/master/lib/magic/game/combat_phase.rb"
    click StackEntity "https://github.com/radar/mtg/blob/master/lib/magic/stack.rb"
    click Actions "https://github.com/radar/mtg/tree/master/lib/magic/actions/"
    click EffectRes "https://github.com/radar/mtg/tree/master/lib/magic/effects/"
    click StaticMgr "https://github.com/radar/mtg/blob/master/lib/magic/static_ability.rb"
    click Replacement "https://github.com/radar/mtg/blob/master/lib/magic/replacement_effect.rb"
    click Triggered "https://github.com/radar/mtg/tree/master/lib/magic/triggered_ability/"
    click EventBase "https://github.com/radar/mtg/blob/master/lib/magic/events/base.rb"
    click Mana "https://github.com/radar/mtg/blob/master/lib/magic/mana.rb"
    click Cost "https://github.com/radar/mtg/tree/master/lib/magic/costs/"
    click Counter "https://github.com/radar/mtg/tree/master/lib/magic/counters/"
    click Filter "https://github.com/radar/mtg/blob/master/lib/magic/filter.rb"
    click Target "https://github.com/radar/mtg/tree/master/lib/magic/targets/"
    click CLI "https://github.com/radar/mtg/tree/master/bin/console"
    click Rake "https://github.com/radar/mtg/tree/master/Rakefile"
    click Pack "https://github.com/radar/mtg/blob/master/magic.gemspec"
    click Test "https://github.com/radar/mtg/tree/master/spec/"

    %% Styles
    classDef domain fill:#ADD8E6,stroke:#000
    classDef engine fill:#90EE90,stroke:#000
    classDef extension fill:#FFA500,stroke:#000
    classDef tooling fill:#D3D3D3,stroke:#000
```
