# walpth/charge-grinder architecture

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

- Interactive diagram: https://gitdiagram.com/walpth/charge-grinder
- Repository: https://github.com/walpth/charge-grinder

## Overview

Charge Grinder is a desktop automation bot for Limbus Company: the user configures teams and priorities, starts a run, and the bot reads the displayed game, chooses actions, and sends mouse/keyboard input. The documented run spans team selection, floor-pack and route choices, events and battles, then shop gift fusion; Luxcavation is a separate grind mode. The graph also shows the GUI/configuration layer and platform input/capture backends. README capabilities inform the domain branches; sampled excerpts are partial, so uncertain internal call links are omitted.

Main entry points: [`source/move.py`](https://github.com/walpth/charge-grinder/blob/main/source/move.py) (Mirror Dungeon), [`Bot.py`](https://github.com/walpth/charge-grinder/blob/main/Bot.py) (Bot orchestrator), [`source/utils/utils.py`](https://github.com/walpth/charge-grinder/blob/main/source/utils/utils.py) (Image and action utilities), [`App.py`](https://github.com/walpth/charge-grinder/blob/main/App.py) (Application UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop UI"]
  node_app["Application UI<br/>[App.py]"]
  node_ui_run["UI run controls<br/>[run.py]"]
  node_settings["Settings manager"]
end

subgraph group_runtime["Run control"]
  node_runner["Bot orchestrator<br/>[Bot.py]"]
  node_md_run["Mirror Dungeon<br/>[move.py]"]
  node_lux["Luxcavation<br/>[lux.py]"]
end

subgraph group_decisions["Game decisions"]
  node_team["Team selection<br/>[teams.py]"]
  node_pack["Floor packs<br/>[pack.py]"]
  node_route["Route movement<br/>[move.py]"]
  node_event["Events<br/>[event.py]"]
  node_battle["Battle handling<br/>[battle.py]"]
  node_shop["Gift shop<br/>[shop.py]"]
end

subgraph group_platform["Desktop interaction"]
  node_grab["Screen capture<br/>[grab.py]"]
  node_utils["Image and action utilities<br/>[utils.py]"]
  node_os_backend["OS backends"]
  node_x11["X11 backend<br/>[os_x11_backend.py]"]
  node_wayland["Wayland backend"]
  node_movement["Mouse movement<br/>[builder.py]"]
  node_bridge["Input bridge<br/>[bridge.py]"]
  node_profiles["Input profiles<br/>[profiles.py]"]
end

subgraph group_integrations["Reporting and state"]
  node_state["Run statistics<br/>[stats.py]"]
  node_webhook["Discord reporting<br/>[discord_webhook.py]"]
end

node_user(("User"))
node_game(("Game window"))
node_discord(("Discord webhook service"))

node_user -->|"configures and starts"| node_app
node_app -->|"reads and saves"| node_settings
node_app -->|"starts run"| node_ui_run
node_ui_run -->|"dispatches"| node_runner
node_runner -->|"runs dungeon"| node_md_run
node_runner -->|"runs grind"| node_lux
node_md_run -->|"selects team"| node_team
node_md_run -->|"selects packs"| node_pack
node_md_run -->|"chooses next node"| node_route
node_md_run -->|"handles event"| node_event
node_md_run -->|"handles encounter"| node_battle
node_md_run -->|"manages gifts"| node_shop
node_team -->|"reads and selects"| node_game
node_pack -->|"reads and selects"| node_game
node_route -->|"reads and moves"| node_game
node_event -->|"reads and acts"| node_game
node_battle -->|"reads and acts"| node_game
node_shop -->|"reads and buys"| node_game
node_lux -->|"reads and acts"| node_game
node_runner -->|"captures screen"| node_grab
node_grab -->|"provides images"| node_utils
node_utils -->|"uses platform input"| node_os_backend
node_utils -.->|"uses platform input"| node_x11
node_utils -.->|"uses platform input"| node_wayland
node_utils -->|"builds pointer motion"| node_movement
node_movement -->|"uses profiles"| node_profiles
node_utils -->|"sends input"| node_bridge
node_runner -->|"records run metrics"| node_state
node_runner -->|"emits run events"| node_webhook
node_webhook -.->|"sends notifications"| node_discord

click node_app "https://github.com/walpth/charge-grinder/blob/main/App.py"
click node_ui_run "https://github.com/walpth/charge-grinder/blob/main/source_app/run.py"
click node_settings "https://github.com/walpth/charge-grinder/blob/main/source_app/settings_manager.py"
click node_runner "https://github.com/walpth/charge-grinder/blob/main/Bot.py"
click node_md_run "https://github.com/walpth/charge-grinder/blob/main/source/move.py"
click node_team "https://github.com/walpth/charge-grinder/blob/main/source/teams.py"
click node_pack "https://github.com/walpth/charge-grinder/blob/main/source/pack.py"
click node_route "https://github.com/walpth/charge-grinder/blob/main/source/move.py"
click node_event "https://github.com/walpth/charge-grinder/blob/main/source/event.py"
click node_battle "https://github.com/walpth/charge-grinder/blob/main/source/battle.py"
click node_shop "https://github.com/walpth/charge-grinder/blob/main/source/shop.py"
click node_lux "https://github.com/walpth/charge-grinder/blob/main/source/lux.py"
click node_grab "https://github.com/walpth/charge-grinder/blob/main/source/grab.py"
click node_utils "https://github.com/walpth/charge-grinder/blob/main/source/utils/utils.py"
click node_os_backend "https://github.com/walpth/charge-grinder/blob/main/source/utils/os_windows_backend.py"
click node_x11 "https://github.com/walpth/charge-grinder/blob/main/source/utils/os_x11_backend.py"
click node_wayland "https://github.com/walpth/charge-grinder/blob/main/source/utils/os_wayland_backend.py"
click node_movement "https://github.com/walpth/charge-grinder/blob/main/source/utils/movement/builder.py"
click node_bridge "https://github.com/walpth/charge-grinder/blob/main/source/utils/bridge/bridge.py"
click node_profiles "https://github.com/walpth/charge-grinder/blob/main/source/utils/profiles.py"
click node_state "https://github.com/walpth/charge-grinder/blob/main/stats.py"
click node_webhook "https://github.com/walpth/charge-grinder/blob/main/source/utils/discord_webhook.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_app,node_ui_run,node_settings,node_user toneBlue
class node_runner,node_md_run,node_lux toneAmber
class node_team,node_pack,node_route,node_event,node_battle,node_shop,node_discord toneMint
class node_grab,node_utils,node_os_backend,node_x11,node_wayland,node_movement,node_bridge,node_profiles toneRose
class node_state,node_webhook,node_game toneIndigo
```

## Components

### Desktop UI

- [Application UI](https://github.com/walpth/charge-grinder/blob/main/App.py): `App.py`
- [UI run controls](https://github.com/walpth/charge-grinder/blob/main/source_app/run.py): `source_app/run.py`
- [Settings manager](https://github.com/walpth/charge-grinder/blob/main/source_app/settings_manager.py): `source_app/settings_manager.py`

### Run control

- [Bot orchestrator](https://github.com/walpth/charge-grinder/blob/main/Bot.py): `Bot.py`
- [Mirror Dungeon](https://github.com/walpth/charge-grinder/blob/main/source/move.py): `source/move.py`
- [Luxcavation](https://github.com/walpth/charge-grinder/blob/main/source/lux.py): `source/lux.py`

### Game decisions

- [Team selection](https://github.com/walpth/charge-grinder/blob/main/source/teams.py): `source/teams.py`
- [Floor packs](https://github.com/walpth/charge-grinder/blob/main/source/pack.py): `source/pack.py`
- [Route movement](https://github.com/walpth/charge-grinder/blob/main/source/move.py): `source/move.py`
- [Events](https://github.com/walpth/charge-grinder/blob/main/source/event.py): `source/event.py`
- [Battle handling](https://github.com/walpth/charge-grinder/blob/main/source/battle.py): `source/battle.py`
- [Gift shop](https://github.com/walpth/charge-grinder/blob/main/source/shop.py): `source/shop.py`

### Desktop interaction

- [Screen capture](https://github.com/walpth/charge-grinder/blob/main/source/grab.py): `source/grab.py`
- [Image and action utilities](https://github.com/walpth/charge-grinder/blob/main/source/utils/utils.py): `source/utils/utils.py`
- [OS backends](https://github.com/walpth/charge-grinder/blob/main/source/utils/os_windows_backend.py): `source/utils/os_windows_backend.py`
- [X11 backend](https://github.com/walpth/charge-grinder/blob/main/source/utils/os_x11_backend.py): `source/utils/os_x11_backend.py`
- [Wayland backend](https://github.com/walpth/charge-grinder/blob/main/source/utils/os_wayland_backend.py): `source/utils/os_wayland_backend.py`
- [Mouse movement](https://github.com/walpth/charge-grinder/blob/main/source/utils/movement/builder.py): `source/utils/movement/builder.py`
- [Input bridge](https://github.com/walpth/charge-grinder/blob/main/source/utils/bridge/bridge.py): `source/utils/bridge/bridge.py`
- [Input profiles](https://github.com/walpth/charge-grinder/blob/main/source/utils/profiles.py): `source/utils/profiles.py`

### Reporting and state

- [Run statistics](https://github.com/walpth/charge-grinder/blob/main/stats.py): `stats.py`
- [Discord reporting](https://github.com/walpth/charge-grinder/blob/main/source/utils/discord_webhook.py): `source/utils/discord_webhook.py`

### Other components

- **User**
- **Game window**
- **Discord webhook service**

## Connections

- User → Application UI: configures and starts
- Application UI → Settings manager: reads and saves
- Application UI → UI run controls: starts run
- UI run controls → Bot orchestrator: dispatches
- Bot orchestrator → Mirror Dungeon: runs dungeon
- Bot orchestrator → Luxcavation: runs grind
- Mirror Dungeon → Team selection: selects team
- Mirror Dungeon → Floor packs: selects packs
- Mirror Dungeon → Route movement: chooses next node
- Mirror Dungeon → Events: handles event
- Mirror Dungeon → Battle handling: handles encounter
- Mirror Dungeon → Gift shop: manages gifts
- Team selection → Game window: reads and selects
- Floor packs → Game window: reads and selects
- Route movement → Game window: reads and moves
- Events → Game window: reads and acts
- Battle handling → Game window: reads and acts
- Gift shop → Game window: reads and buys
- Luxcavation → Game window: reads and acts
- Bot orchestrator → Screen capture: captures screen
- Screen capture → Image and action utilities: provides images
- Image and action utilities → OS backends: uses platform input
- Image and action utilities → X11 backend: uses platform input
- Image and action utilities → Wayland backend: uses platform input
- Image and action utilities → Mouse movement: builds pointer motion
- Mouse movement → Input profiles: uses profiles
- Image and action utilities → Input bridge: sends input
- Bot orchestrator → Run statistics: records run metrics
- Bot orchestrator → Discord reporting: emits run events
- Discord reporting → Discord webhook service: sends notifications