# magicstrangelzb/hearthstonelegendarriver architecture

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

- Interactive diagram: https://gitdiagram.com/magicstrangelzb/hearthstonelegendarriver
- Repository: https://github.com/magicstrangelzb/hearthstonelegendarriver

## Overview

HSLegendArriver automates Hearthstone matches from a browser-based control panel: users configure and calibrate the screen, start automation, and the runtime observes game state, processes recommendation-panel text, validates actions, and clicks through the game. Separate branches provide environment checks, live logs and overlays, and Hearthstone liveness monitoring. The recommendation flow excerpt shows execution and result verification; several other connections are based on the SOURCE INDEX or README rather than inspected implementation, so those links are limited to documented or indexed relationships.

Main entry points: [`web_ui.py`](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/web_ui.py) (Web console), [`FSM_action.py`](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/FSM_action.py) (Match automation), [`src/flow/recommendation_flow.py`](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/flow/recommendation_flow.py) (Recommendation execution), [`src/capture/desktop_capture.py`](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/capture/desktop_capture.py) (Recommendation capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control and actions"]
  node_fsm["Match automation<br/>[FSM_action.py]"]
  node_manual["Manual controller"]
  node_click["Game clicks<br/>[click.py]"]
  node_strategy["Strategy logic<br/>[strategy.py]"]
end

subgraph group_recommend["Recommendation processing"]
  node_capture["Recommendation capture<br/>[desktop_capture.py]"]
  node_ocr["Paddle OCR<br/>[paddle_adapter.py]"]
  node_preprocess["OCR preprocessing<br/>[preprocess.py]"]
  node_reader["Stable OCR reader<br/>[stable_reader.py]"]
  node_parser["Instruction parser"]
  node_models["Recommendation protocol"]
  node_flow["Recommendation execution"]
  node_adapter["Action adapter"]
end

subgraph group_game["Game state and safety"]
  node_validator["Recommendation validator"]
  node_screen["Screen state detection<br/>[get_screen.py]"]
  node_liveness["Liveness monitor"]
end

subgraph group_operator["Operator tools"]
  node_webui["Web console<br/>[web_ui.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_regions["Screen regions<br/>[screen_regions.py]"]
  node_region_overlay["Calibration overlay<br/>[region_overlay.py]"]
  node_selfcheck["Environment checks<br/>[selfcheck.py]"]
end

subgraph group_observability["Logs and status"]
  node_log_overlay["Log overlay<br/>[log_overlay.py]"]
  node_logstate["Automation status<br/>[log_state.py]"]
  node_logop["Log processing<br/>[log_op.py]"]
  node_powerlog[("Power log<br/>[power_log.py]")]
  node_printinfo["Console reporting<br/>[print_info.py]"]
end

node_user(("Operator"))
node_browser(("Browser UI"))
node_hearthstone(("Hearthstone"))
node_hsbox(("Hearthstone Box"))

node_user -->|"uses"| node_browser
node_browser -->|"controls"| node_webui
node_webui -->|"starts automation"| node_fsm
node_webui -->|"runs checks"| node_selfcheck
node_webui -->|"configures regions"| node_regions
node_webui -->|"toggles calibration"| node_region_overlay
node_webui -->|"shows overlay"| node_log_overlay
node_webui -->|"shows status"| node_liveness
node_config -->|"provides coordinates"| node_regions
node_regions -->|"uses state detection"| node_screen
node_regions -->|"configures capture"| node_capture
node_region_overlay -->|"displays regions"| node_regions
node_fsm -->|"reads game state"| node_screen
node_fsm -->|"runs recommendation flow"| node_flow
node_fsm -->|"uses controller"| node_manual
node_fsm -->|"uses strategy"| node_strategy
node_fsm -->|"updates status"| node_logstate
node_fsm -->|"checks liveness"| node_liveness
node_flow -.->|"obtains frames"| node_capture
node_flow -.->|"reads recommendation"| node_reader
node_flow -.->|"parses instruction"| node_parser
node_flow -->|"validates action"| node_validator
node_flow -.->|"adapts action"| node_adapter
node_flow -->|"executes action"| node_manual
node_manual -->|"issues clicks"| node_click
node_capture -->|"creates evidence"| node_models
node_ocr -->|"creates OCR evidence"| node_models
node_reader -->|"uses preprocessing"| node_preprocess
node_parser -->|"creates proposal"| node_models
node_adapter -->|"maps proposal"| node_models
node_liveness -->|"checks freshness"| node_powerlog
node_logop -->|"reads log"| node_powerlog
node_logstate -->|"uses log processing"| node_logop
node_logstate -->|"reports status"| node_printinfo
node_webui -->|"reads status"| node_logstate
node_webui -->|"uses logging"| node_logop
node_capture -->|"captures desktop"| node_hearthstone
node_capture -->|"checks panel"| node_hsbox
node_click -->|"operates game"| node_hearthstone
node_selfcheck -->|"checks installation"| node_hearthstone

click node_webui "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/web_ui.py"
click node_fsm "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/FSM_action.py"
click node_manual "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/manual_controller.py"
click node_click "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/click.py"
click node_strategy "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/strategy.py"
click node_capture "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/capture/desktop_capture.py"
click node_ocr "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/ocr/paddle_adapter.py"
click node_preprocess "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/ocr/preprocess.py"
click node_reader "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/ocr/stable_reader.py"
click node_parser "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/parser/recommendation_parser.py"
click node_models "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/recommendation_models.py"
click node_flow "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/flow/recommendation_flow.py"
click node_adapter "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/game_state/recommendation_adapter.py"
click node_validator "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/safety/recommendation_validator.py"
click node_screen "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/get_screen.py"
click node_liveness "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/safety/hearthstone_liveness.py"
click node_config "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/config.py"
click node_regions "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/screen_regions.py"
click node_region_overlay "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/region_overlay.py"
click node_selfcheck "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/selfcheck.py"
click node_log_overlay "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/log_overlay.py"
click node_logstate "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/log_state.py"
click node_logop "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/log_op.py"
click node_powerlog "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/power_log.py"
click node_printinfo "https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/print_info.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_fsm,node_manual,node_click,node_strategy,node_browser toneBlue
class node_capture,node_ocr,node_preprocess,node_reader,node_parser,node_models,node_flow,node_adapter toneAmber
class node_validator,node_screen,node_liveness toneMint
class node_webui,node_config,node_regions,node_region_overlay,node_selfcheck toneRose
class node_log_overlay,node_logstate,node_logop,node_powerlog,node_printinfo,node_user,node_hearthstone,node_hsbox toneIndigo
```

## Components

### Control and actions

- [Match automation](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/FSM_action.py): `FSM_action.py`
- [Manual controller](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/manual_controller.py): `manual_controller.py`
- [Game clicks](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/click.py): `click.py`
- [Strategy logic](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/strategy.py): `strategy.py`

### Recommendation processing

- [Recommendation capture](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/capture/desktop_capture.py): `src/capture/desktop_capture.py`
- [Paddle OCR](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/ocr/paddle_adapter.py): `src/ocr/paddle_adapter.py`
- [OCR preprocessing](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/ocr/preprocess.py): `src/ocr/preprocess.py`
- [Stable OCR reader](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/ocr/stable_reader.py): `src/ocr/stable_reader.py`
- [Instruction parser](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/parser/recommendation_parser.py): `src/parser/recommendation_parser.py`
- [Recommendation protocol](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/recommendation_models.py): `src/recommendation_models.py`
- [Recommendation execution](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/flow/recommendation_flow.py): `src/flow/recommendation_flow.py`
- [Action adapter](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/game_state/recommendation_adapter.py): `src/game_state/recommendation_adapter.py`

### Game state and safety

- [Recommendation validator](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/safety/recommendation_validator.py): `src/safety/recommendation_validator.py`
- [Screen state detection](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/get_screen.py): `get_screen.py`
- [Liveness monitor](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/src/safety/hearthstone_liveness.py): `src/safety/hearthstone_liveness.py`

### Operator tools

- [Web console](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/web_ui.py): `web_ui.py`
- [Runtime configuration](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/config.py): `config.py`
- [Screen regions](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/screen_regions.py): `screen_regions.py`
- [Calibration overlay](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/region_overlay.py): `region_overlay.py`
- [Environment checks](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/selfcheck.py): `selfcheck.py`

### Logs and status

- [Log overlay](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/log_overlay.py): `log_overlay.py`
- [Automation status](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/log_state.py): `log_state.py`
- [Log processing](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/log_op.py): `log_op.py`
- [Power log](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/power_log.py): `power_log.py`
- [Console reporting](https://github.com/magicstrangelzb/hearthstonelegendarriver/blob/main/print_info.py): `print_info.py`

### Other components

- **Operator**
- **Browser UI**
- **Hearthstone**
- **Hearthstone Box**

## Connections

- Operator → Browser UI: uses
- Browser UI → Web console: controls
- Web console → Match automation: starts automation (evidence: `web_ui.py`)
- Web console → Environment checks: runs checks (evidence: `web_ui.py`)
- Web console → Screen regions: configures regions (evidence: `web_ui.py`)
- Web console → Calibration overlay: toggles calibration (evidence: `web_ui.py`)
- Web console → Log overlay: shows overlay (evidence: `web_ui.py`)
- Web console → Liveness monitor: shows status (evidence: `web_ui.py`)
- Runtime configuration → Screen regions: provides coordinates (evidence: `config.py`)
- Screen regions → Screen state detection: uses state detection (evidence: `screen_regions.py`)
- Screen regions → Recommendation capture: configures capture (evidence: `screen_regions.py`)
- Calibration overlay → Screen regions: displays regions (evidence: `region_overlay.py`)
- Match automation → Screen state detection: reads game state (evidence: `FSM_action.py`)
- Match automation → Recommendation execution: runs recommendation flow (evidence: `FSM_action.py`)
- Match automation → Manual controller: uses controller (evidence: `FSM_action.py`)
- Match automation → Strategy logic: uses strategy (evidence: `FSM_action.py`)
- Match automation → Automation status: updates status (evidence: `FSM_action.py`)
- Match automation → Liveness monitor: checks liveness (evidence: `FSM_action.py`)
- Recommendation execution → Recommendation capture: obtains frames
- Recommendation execution → Stable OCR reader: reads recommendation
- Recommendation execution → Instruction parser: parses instruction
- Recommendation execution → Recommendation validator: validates action (evidence: `src/flow/recommendation_flow.py`)
- Recommendation execution → Action adapter: adapts action
- Recommendation execution → Manual controller: executes action (evidence: `src/flow/recommendation_flow.py`)
- Manual controller → Game clicks: issues clicks (evidence: `manual_controller.py`)
- Recommendation capture → Recommendation protocol: creates evidence (evidence: `src/capture/desktop_capture.py`)
- Paddle OCR → Recommendation protocol: creates OCR evidence (evidence: `src/ocr/paddle_adapter.py`)
- Stable OCR reader → OCR preprocessing: uses preprocessing (evidence: `src/ocr/stable_reader.py`)
- Instruction parser → Recommendation protocol: creates proposal (evidence: `src/parser/recommendation_parser.py`)
- Action adapter → Recommendation protocol: maps proposal (evidence: `src/game_state/recommendation_adapter.py`)
- Liveness monitor → Power log: checks freshness (evidence: `src/safety/hearthstone_liveness.py`)
- Log processing → Power log: reads log (evidence: `log_op.py`)
- Automation status → Log processing: uses log processing (evidence: `log_state.py`)
- Automation status → Console reporting: reports status (evidence: `log_state.py`)
- Web console → Automation status: reads status (evidence: `web_ui.py`)
- Web console → Log processing: uses logging (evidence: `web_ui.py`)
- Recommendation capture → Hearthstone: captures desktop (evidence: `src/capture/desktop_capture.py`)
- Recommendation capture → Hearthstone Box: checks panel (evidence: `src/capture/desktop_capture.py`)
- Game clicks → Hearthstone: operates game
- Environment checks → Hearthstone: checks installation (evidence: `selfcheck.py`)
