How b4tiste/bot-swbox works
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: commands/mod.rs commands mod · shared/mod.rs shared · upload_json/mod.rs upload json · mob_stats/mod.rs mob stats
Components 26
Runtime
Discord bot entrypoint and command dispatch.
- main · Bootstraps the bot and routes Discord events into command handling.
src/main.rs - commands mod · 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 · Cross-cutting helpers for embeds, logging, aliases, coupons, and shared models.
src/commands/shared/mod.rs - player stats · Resolves player identity and surfaces rank, history, and account summaries.
src/commands/player_stats/mod.rs - leaderboard · Fetches and pages leaderboard data with player selection interactions.
src/commands/leaderboard/mod.rs - mob stats · Monster lookup and stat presentation with modal/autocomplete interactions.
src/commands/mob_stats/mod.rs - how to build · Build and rune recommendation flow for monsters.
src/commands/how_to_build/mod.rs - best pve teams · Searches or ranks effective PvE team compositions.
src/commands/best_pve_teams/mod.rs - rta core · Analyzes RTA/Siege exports and scores trios with cached ranking logic.
src/commands/rta_core/mod.rs - replays · Surfaces replay-related stats and summaries.
src/commands/replays/mod.rs - upload json · Parses uploaded account JSON and computes scoring or comparison outputs.
src/commands/upload_json/mod.rs - register · Handles player registration, alias tracking, and unregistration.
src/commands/register/mod.rs - player names · Tracks and edits player name mappings through modal-driven input.
src/commands/player_names/mod.rs - ranks · Provides rank-related lookup and presentation utilities.
src/commands/ranks/mod.rs - mystats · User-facing personal statistics command surface.
src/commands/mystats/mod.rs - meta · Supports broader gameplay meta summaries and derived views.
src/commands/meta/mod.rs - services · Auxiliary service-oriented command surface.
src/commands/services/mod.rs - suggestion · Collects structured user suggestions through modal interaction.
src/commands/suggestion/mod.rs - support · 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 · Static monster catalog used for lookup and enrichment.
monsters_catalog.json - monster elements · Static monster element mapping used by monster-related features.
monsters_elements.json - avg rune stats · Average monster rune/stat dataset used for build advice.
assets/avg_runes/average_monster_stats.json - monster images · Image assets embedded in Discord responses.
assets/monster_images
Ops
Deployment and user-facing policy/documentation.
- deploy workflow · GitHub Actions workflow for automated deployment to the target host.
.github/workflows/deploy-pi.yml - README · Primary repository documentation and feature overview.
README.md - policy docs · Privacy and terms documents governing uploads and user data handling.
privacy-policy.md
Connections 32
- 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.