# b4tiste/bot-swbox architecture

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

- Interactive diagram: https://gitdiagram.com/b4tiste/bot-swbox
- Repository: https://github.com/b4tiste/bot-swbox

## Overview

1. **Overall shape**
   - `bot-swbox` is a Rust Discord bot centered on slash-command interactions for Summoners War data.
   - The architecture is feature-module based: each command lives in its own `src/commands/<feature>` directory, with `main.rs` acting as the entrypoint and command dispatcher.

2. **Execution boundary**
   - The runtime boundary is Discord itself: users trigger slash commands, select menus, buttons, and modals.
   - Command handlers build Discord embeds and interactive responses rather than serving HTTP or running as a standalone CLI.

3. **Command subsystem**
   - `src/commands` is the primary application layer.
   - Each submodule represents a user-facing capability such as `player_stats`, `mob_stats`, `leaderboard`, `rta_core`, `replays`, `how_to_build`, `upload_json`, `register`, `suggestion`, and `help`.
   - Most features are split into handler files plus supporting `models`, `utils`, `modal`, or `cache` modules.

4. **Interactive flows**
   - Several commands are multi-step workflows:
     - `/get_rta_leaderboard` uses pagination and player selection.
     - `/get_duo_stats`, `/track_player_names`, and `/send_suggestion` open modals for structured input.
     - `/get_mob_stats` and similar commands use autocomplete or rank selection.
   - This means the bot is not just request/response; it maintains short-lived interaction state across Discord component events.

5. **Data-source layer**
   - The bot pulls game intelligence from external community/game data sources referenced in the README: **SWARENA**, **SWARFARM**, and **SWRT**.
   - The feature set suggests a mix of live API access and curated local datasets, especially for ranks, monster metadata, and replay/stat lookups.

6. **Local reference data**
   - The repository includes static assets and catalogs that act as lookup/reference data:
     - `monsters_catalog.json`
     - `monsters_elements.json`
     - `assets/avg_runes/average_monster_stats.json`
     - `assets/monster_images/`
   - These likely support monster identification, element/2A prioritization, rune recommendations, and embed images.

7. **Analytics and scoring flows**
   - Several commands are data-analysis pipelines rather than simple lookups:
     - `/upload_json` parses an exported account JSON and computes account/rune scores.
     - `/get_rta_core` analyzes RTA/Siege export JSON and ranks trios using win rate, pick count, late-pick penalty, and LD bonuses.
   - These flows are file-ingestion boundaries: user-uploaded JSON enters the bot, gets parsed and scored, then is summarized back into Discord output.

8. **Player-centric features**
   - `player_stats`, `leaderboard`, `player_names`, `register`, and `mystats` form the player identity and profile area.
   - This subsystem resolves player names/IDs, tracks aliases, and surfaces rank, win rate, LD5s, top monsters, and replay history.
   - The README indicates some of this data is persisted over time, especially for account-score comparison in `/upload_json`.

9. **Combat/statistics features**
   - `mob_stats`, `best_pve_teams`, `how_to_build`, `duo_stats`, and `replays` are focused on monster composition and battle outcomes.
   - These commands likely combine external stats with local metadata to answer “what to build,” “what works together,” and “what counters what.”

10. **Shared cross-cutting utilities**
    - `src/commands/shared` holds common concerns reused across commands:
      - error/embed handling
      - logging
      - player alias resolution
      - coupon/shared models
    - This is the main boundary for code that is not feature-specific and likely prevents duplication across command modules.

11. **Legacy/archived code**
    - `archived_commands` contains older implementations such as `duo_stats` and `register`.
    - Architecturally, this is a historical reference area rather than the active command surface; the active versions live under `src/commands`.

12. **Operational/deployment boundary**
    - The repository includes a GitHub Actions workflow at `.github/workflows/deploy-pi.yml`, indicating automated deployment to a Raspberry Pi or similar self-hosted target.
    - This suggests the bot is deployed as a long-running service, not a serverless or purely local tool.

13. **Non-code documentation and policy**
    - `README.md`, `privacy-policy.md`, and `terms-of-services.md` define user-facing behavior, data usage, and support channels.
    - These docs matter architecturally because the bot handles user uploads, account tracking, and suggestion/reporting flows that touch personal or gameplay data.

14. **Diagram-friendly summary**
    - The cleanest architecture view is: **Discord user interaction → command dispatcher (`main.rs` + `src/commands`) → feature-specific analysis/lookup → shared utilities/local assets/external game-data services → Discord embed/modal response**.
    - A second important path is **JSON file upload → parsing/scoring module → persisted or summarized result → Discord response**.

Main entry points: [`src/commands/mod.rs`](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/mod.rs) (commands mod), [`src/commands/shared/mod.rs`](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/shared/mod.rs) (shared), [`src/commands/upload_json/mod.rs`](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/upload_json/mod.rs) (upload json), [`src/commands/mob_stats/mod.rs`](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/mob_stats/mod.rs) (mob stats)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime"]
  node_node_main(("main<br/>entrypoint<br/>[main.rs]"))
  node_node_commands_mod["commands mod<br/>dispatcher<br/>[mod.rs]"]
end

subgraph group_grp_commands["Commands"]
  node_node_shared["shared<br/>common utilities<br/>[mod.rs]"]
  node_node_player_stats["player stats<br/>profile lookup<br/>[mod.rs]"]
  node_node_leaderboard["leaderboard<br/>ranking flow<br/>[mod.rs]"]
  node_node_mob_stats["mob stats<br/>monster stats<br/>[mod.rs]"]
  node_node_how_to_build["how to build<br/>build advice<br/>[mod.rs]"]
  node_node_best_pve["best pve teams<br/>team analysis<br/>[mod.rs]"]
  node_node_rta_core["rta core<br/>scoring pipeline<br/>[mod.rs]"]
  node_node_replays["replays<br/>battle history<br/>[mod.rs]"]
  node_node_upload_json["upload json<br/>file ingest<br/>[mod.rs]"]
  node_node_register["register<br/>identity setup<br/>[mod.rs]"]
  node_node_player_names["player names<br/>alias tracking<br/>[mod.rs]"]
  node_node_ranks["ranks<br/>rank lookup<br/>[mod.rs]"]
  node_node_mystats["mystats<br/>personal stats<br/>[mod.rs]"]
  node_node_meta["meta<br/>[mod.rs]"]
  node_node_services["services<br/>service surface<br/>[mod.rs]"]
  node_node_suggestion["suggestion<br/>feedback flow<br/>[mod.rs]"]
  node_node_support["support<br/>helpdesk<br/>[mod.rs]"]
end

subgraph group_grp_data["Data"]
  node_node_monsters_catalog["monsters catalog<br/>reference data"]
  node_node_monsters_elements["monster elements<br/>reference data"]
  node_node_avg_stats["avg rune stats<br/>reference data"]
  node_node_monster_images[("monster images<br/>asset set")]
end

subgraph group_grp_ops["Ops"]
  node_node_deploy["deploy workflow<br/>ci/deploy<br/>[deploy-pi.yml]"]
  node_node_readme["README<br/>docs<br/>[README.md]"]
  node_node_policy["policy docs<br/>[privacy-policy.md]"]
end

node_node_main -->|"dispatches"| node_node_commands_mod
node_node_commands_mod -->|"reuses"| node_node_shared
node_node_commands_mod -->|"loads"| node_node_player_stats
node_node_commands_mod -->|"loads"| node_node_leaderboard
node_node_commands_mod -->|"loads"| node_node_mob_stats
node_node_commands_mod -->|"loads"| node_node_how_to_build
node_node_commands_mod -->|"loads"| node_node_best_pve
node_node_commands_mod -->|"loads"| node_node_rta_core
node_node_commands_mod -->|"loads"| node_node_replays
node_node_commands_mod -->|"loads"| node_node_upload_json
node_node_commands_mod -->|"loads"| node_node_register
node_node_commands_mod -->|"loads"| node_node_player_names
node_node_commands_mod -->|"loads"| node_node_ranks
node_node_commands_mod -->|"loads"| node_node_mystats
node_node_commands_mod -->|"loads"| node_node_meta
node_node_commands_mod -->|"loads"| node_node_services
node_node_commands_mod -->|"loads"| node_node_suggestion
node_node_commands_mod -->|"loads"| node_node_support
node_node_mob_stats -->|"looks up"| node_node_monsters_catalog
node_node_mob_stats -->|"uses"| node_node_monsters_elements
node_node_how_to_build -->|"uses"| node_node_avg_stats
node_node_how_to_build -->|"renders"| node_node_monster_images
node_node_best_pve -->|"looks up"| node_node_monsters_catalog
node_node_rta_core -.->|"shares parsing"| node_node_upload_json
node_node_rta_core -->|"reuses"| node_node_shared
node_node_upload_json -->|"reuses"| node_node_shared
node_node_player_names -->|"reuses"| node_node_shared
node_node_register -->|"reuses"| node_node_shared
node_node_leaderboard -->|"reuses"| node_node_shared
node_node_deploy -.->|"deploys"| node_node_main
node_node_readme -.->|"documents"| node_node_commands_mod
node_node_policy -.->|"governs"| node_node_upload_json

click node_node_main "https://github.com/b4tiste/bot-swbox/blob/main/src/main.rs"
click node_node_commands_mod "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/mod.rs"
click node_node_shared "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/shared/mod.rs"
click node_node_player_stats "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/player_stats/mod.rs"
click node_node_leaderboard "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/leaderboard/mod.rs"
click node_node_mob_stats "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/mob_stats/mod.rs"
click node_node_how_to_build "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/how_to_build/mod.rs"
click node_node_best_pve "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/best_pve_teams/mod.rs"
click node_node_rta_core "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/rta_core/mod.rs"
click node_node_replays "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/replays/mod.rs"
click node_node_upload_json "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/upload_json/mod.rs"
click node_node_register "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/register/mod.rs"
click node_node_player_names "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/player_names/mod.rs"
click node_node_ranks "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/ranks/mod.rs"
click node_node_mystats "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/mystats/mod.rs"
click node_node_meta "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/meta/mod.rs"
click node_node_services "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/services/mod.rs"
click node_node_suggestion "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/suggestion/mod.rs"
click node_node_support "https://github.com/b4tiste/bot-swbox/blob/main/src/commands/support/mod.rs"
click node_node_monsters_catalog "https://github.com/b4tiste/bot-swbox/blob/main/monsters_catalog.json"
click node_node_monsters_elements "https://github.com/b4tiste/bot-swbox/blob/main/monsters_elements.json"
click node_node_avg_stats "https://github.com/b4tiste/bot-swbox/blob/main/assets/avg_runes/average_monster_stats.json"
click node_node_monster_images "https://github.com/b4tiste/bot-swbox/tree/main/assets/monster_images"
click node_node_deploy "https://github.com/b4tiste/bot-swbox/blob/main/.github/workflows/deploy-pi.yml"
click node_node_readme "https://github.com/b4tiste/bot-swbox/blob/main/README.md"
click node_node_policy "https://github.com/b4tiste/bot-swbox/blob/main/privacy-policy.md"

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_node_main,node_node_commands_mod toneBlue
class node_node_shared,node_node_player_stats,node_node_leaderboard,node_node_mob_stats,node_node_how_to_build,node_node_best_pve,node_node_rta_core,node_node_replays,node_node_upload_json,node_node_register,node_node_player_names,node_node_ranks,node_node_mystats,node_node_meta,node_node_services,node_node_suggestion,node_node_support toneAmber
class node_node_monsters_catalog,node_node_monsters_elements,node_node_avg_stats,node_node_monster_images toneMint
class node_node_deploy,node_node_readme,node_node_policy toneRose
```

## Components

### Runtime

Discord bot entrypoint and command dispatch.

- [main](https://github.com/b4tiste/bot-swbox/blob/main/src/main.rs): entrypoint · Bootstraps the bot and routes Discord events into command handling. · `src/main.rs`
- [commands mod](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/mod.rs): dispatcher · Central command registry and module wiring for the feature-based command tree. · `src/commands/mod.rs`

### Commands

Feature modules exposed through slash commands and interactions.

- [shared](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/shared/mod.rs): common utilities · Cross-cutting helpers for embeds, logging, aliases, coupons, and shared models. · `src/commands/shared/mod.rs`
- [player stats](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/player_stats/mod.rs): profile lookup · Resolves player identity and surfaces rank, history, and account summaries. · `src/commands/player_stats/mod.rs`
- [leaderboard](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/leaderboard/mod.rs): ranking flow · Fetches and pages leaderboard data with player selection interactions. · `src/commands/leaderboard/mod.rs`
- [mob stats](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/mob_stats/mod.rs): monster stats · Monster lookup and stat presentation with modal/autocomplete interactions. · `src/commands/mob_stats/mod.rs`
- [how to build](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/how_to_build/mod.rs): build advice · Build and rune recommendation flow for monsters. · `src/commands/how_to_build/mod.rs`
- [best pve teams](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/best_pve_teams/mod.rs): team analysis · Searches or ranks effective PvE team compositions. · `src/commands/best_pve_teams/mod.rs`
- [rta core](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/rta_core/mod.rs): scoring pipeline · Analyzes RTA/Siege exports and scores trios with cached ranking logic. · `src/commands/rta_core/mod.rs`
- [replays](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/replays/mod.rs): battle history · Surfaces replay-related stats and summaries. · `src/commands/replays/mod.rs`
- [upload json](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/upload_json/mod.rs): file ingest · Parses uploaded account JSON and computes scoring or comparison outputs. · `src/commands/upload_json/mod.rs`
- [register](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/register/mod.rs): identity setup · Handles player registration, alias tracking, and unregistration. · `src/commands/register/mod.rs`
- [player names](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/player_names/mod.rs): alias tracking · Tracks and edits player name mappings through modal-driven input. · `src/commands/player_names/mod.rs`
- [ranks](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/ranks/mod.rs): rank lookup · Provides rank-related lookup and presentation utilities. · `src/commands/ranks/mod.rs`
- [mystats](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/mystats/mod.rs): personal stats · User-facing personal statistics command surface. · `src/commands/mystats/mod.rs`
- [meta](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/meta/mod.rs): meta data · Supports broader gameplay meta summaries and derived views. · `src/commands/meta/mod.rs`
- [services](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/services/mod.rs): service surface · Auxiliary service-oriented command surface. · `src/commands/services/mod.rs`
- [suggestion](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/suggestion/mod.rs): feedback flow · Collects structured user suggestions through modal interaction. · `src/commands/suggestion/mod.rs`
- [support](https://github.com/b4tiste/bot-swbox/blob/main/src/commands/support/mod.rs): helpdesk · Support-oriented command surface and user guidance. · `src/commands/support/mod.rs`

### Data

Local reference datasets and static assets used by command logic.

- [monsters catalog](https://github.com/b4tiste/bot-swbox/blob/main/monsters_catalog.json): reference data · Static monster catalog used for lookup and enrichment. · `monsters_catalog.json`
- [monster elements](https://github.com/b4tiste/bot-swbox/blob/main/monsters_elements.json): reference data · Static monster element mapping used by monster-related features. · `monsters_elements.json`
- [avg rune stats](https://github.com/b4tiste/bot-swbox/blob/main/assets/avg_runes/average_monster_stats.json): reference data · Average monster rune/stat dataset used for build advice. · `assets/avg_runes/average_monster_stats.json`
- [monster images](https://github.com/b4tiste/bot-swbox/tree/main/assets/monster_images): asset set · Image assets embedded in Discord responses. · `assets/monster_images`

### Ops

Deployment and user-facing policy/documentation.

- [deploy workflow](https://github.com/b4tiste/bot-swbox/blob/main/.github/workflows/deploy-pi.yml): ci/deploy · GitHub Actions workflow for automated deployment to the target host. · `.github/workflows/deploy-pi.yml`
- [README](https://github.com/b4tiste/bot-swbox/blob/main/README.md): docs · Primary repository documentation and feature overview. · `README.md`
- [policy docs](https://github.com/b4tiste/bot-swbox/blob/main/privacy-policy.md): docs · Privacy and terms documents governing uploads and user data handling. · `privacy-policy.md`

## Connections

- main → commands mod: dispatches · Entrypoint hands Discord events to the command layer.
- commands mod → shared: reuses · Feature modules share common embed, alias, and logging helpers.
- commands mod → player stats: loads · Registers player profile command handlers.
- commands mod → leaderboard: loads · Registers leaderboard command handlers.
- commands mod → mob stats: loads · Registers monster stats command handlers.
- commands mod → how to build: loads · Registers build-advice command handlers.
- commands mod → best pve teams: loads · Registers PvE team analysis handlers.
- commands mod → rta core: loads · Registers RTA analysis handlers.
- commands mod → replays: loads · Registers replay-related handlers.
- commands mod → upload json: loads · Registers JSON ingestion handlers.
- commands mod → register: loads · Registers identity and registration handlers.
- commands mod → player names: loads · Registers alias-tracking handlers.
- commands mod → ranks: loads · Registers rank lookup handlers.
- commands mod → mystats: loads · Registers personal stats handlers.
- commands mod → meta: loads · Registers meta-analysis handlers.
- commands mod → services: loads · Registers service-oriented handlers.
- commands mod → suggestion: loads · Registers suggestion collection handlers.
- commands mod → support: loads · Registers support handlers.
- mob stats → monsters catalog: looks up · Monster lookup is grounded in the local catalog.
- mob stats → monster elements: uses · Element mapping informs monster filtering and display.
- how to build → avg rune stats: uses · Build recommendations rely on average stat/rune reference data.
- how to build → monster images: renders · Monster images support Discord embeds.
- best pve teams → monsters catalog: looks up · Team analysis enriches monsters from local reference data.
- rta core → upload json: shares parsing · Both features center on uploaded/exported JSON analysis.
- rta core → shared: reuses · Uses shared helpers and common models.
- upload json → shared: reuses · Parsing and reporting reuse shared infrastructure.
- player names → shared: reuses · Alias tracking uses shared player-resolution helpers.
- register → shared: reuses · Registration flows depend on shared identity helpers.
- leaderboard → shared: reuses · Pagination and selection responses use shared embed handling.
- deploy workflow → main: deploys · Workflow ships the bot entrypoint to the runtime host.
- README → commands mod: documents · README describes the command-driven architecture.
- policy docs → upload json: governs · Policy documents matter for uploaded data and account tracking.
