# deyoyk/rankedbedwars architecture

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

- Interactive diagram: https://gitdiagram.com/deyoyk/rankedbedwars
- Repository: https://github.com/deyoyk/rankedbedwars

## Overview

##### Project type and purpose
- This is a Python-based Discord bot (“ranked bedwars discord bot”) that integrates with an external “rbw-hook” to pull in-game events from Bedwars (bedwars1058) and manages ranked game logic (queues, scoring, leaderboards, punishments) via Discord commands.
- Key use cases:
- Real-time game event handling via WebSocket
- Slash-command and prefix-command processing in Discord
- Persistent storage of players, games, queues, ELO scores, punishments, themes, etc.

##### File structure for architectural patterns
- Entry point: bot.py
- Core directories:
- commands/ – command handlers grouped by domain (admin, dev, game, party, player)
- events/ – listeners for Discord events (guild join, voice channel nuke, message nuke, queue join)
- actions/ – discrete units of logic (fix, score image, transcript creation, voiding, etc.)
- managers/ – façade or service classes that orchestrate high-level operations and state (API, database, command dispatch, event dispatch, mute, ban, strikes, party, queue processing, screenshare, permission, websocket)
- managers/websocket/ – WebSocket client, message models, handlers for game, player, queue, scoring, screenshare, voice
- utils/ – helper modules (ELO decay, embed builder, Discord utilities, error handler, daily resets)
- asserts/ – static assets (fonts, themes, games/punishments images)
- themes/ – embed/theme definitions (elite, lunar, rich, y2k)
- configs/ – YAML configuration (bot settings, permissions, season info)
- Persistence: requires MongoDB (recommended to run in same region), accessed via managers/database_manager.py
- Dependencies: Python 3.13.5, discord.py (or equivalent), PyMongo, websockets

##### Extract architecture hints from README
- Real-time integration: “rbw-hook-public” WebSocket feed
- Persists state in MongoDB
- Command/event-driven, modular architecture

##### Main components & interactions
A. External Services
- Discord Gateway & REST API
- rbw-hook WebSocket server (in-game events source)
- MongoDB instance
B. Bot Application
- bot.py (startup & orchestration)
- EventManager (registers listeners from events/)
- CommandManager (routes incoming commands to handlers in commands/)
- WebSocketManager (connects to in-game hook, dispatches to websocket/handlers/)
- DatabaseManager (CRUD operations for players, games, queues, etc.)
- APIManager (if any external HTTP calls)
- Other managers: BanManager, MuteManager, PermissionManager, PartyManager, QueueProcessor, StrikesManager, ScreenshareManager
C. Feature Modules
- Commands (admin, dev, game, party, player) invoking business logic
- Actions (self-contained units for scoring, transcripts, scoring images)
- Themes & Assets (embed templates & static resources)
- Utils (helper routines)

##### Relationships & data flow
1. Bot -> Discord Gateway: receives events (messages, reactions, voice updates), sends messages/embeds
2. Bot -> CommandManager: user invokes command → resolved to specific handler → calls the appropriate Manager(s) or Action(s) → may read/write to DatabaseManager → send response back to user
3. WebSocketManager -> rbw-hook WebSocket: receives real-time game events → dispatches to handlers (game_handler, scoring_handler, etc.) → may trigger Actions or update DB
4. DatabaseManager <-> MongoDB: persistent storage for player profiles, scores, queues, punishments
5. Managers <-> Utils & Themes: build embeds, handle errors, apply ELO decay, format output

##### Architectural patterns & principles
- Event-driven architecture: separation of event listeners (Discord vs WebSocket)
- Command pattern: encapsulating each slash/prefix command in its own module
- Manager/service layer: single responsibility services for domain logic
- Modular plugin-like structure: commands, actions, themes, websocket handlers can be extended independently
- Asynchronous I/O: nonblocking calls to Discord, WebSocket, DB

##### Final checklist
– All major components (Discord, WebSocket hook, Bot core, DB, Command/Event/Action modules)
– Clear boundaries (bot vs external systems vs persistence vs static assets)
– Notes on key patterns (async event loop, manager layer, command routing)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Services
    Discord["Discord Gateway & REST API"]:::external
    Webhook["rbw-hook WebSocket Server"]:::external
    MongoDB["MongoDB"]:::external

    %% Bot Entry Point
    Bot["bot.py"]:::core
    click Bot "https://github.com/deyoyk/rankedbedwars/blob/main/bot.py"

    %% Core Managers
    subgraph "Managers" 
        direction TB
        EventManager["EventManager"]:::manager
        click EventManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/event_manager.py"
        CommandManager["CommandManager"]:::manager
        click CommandManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/command_manager.py"
        WebSocketManager["WebSocketManager"]:::manager
        click WebSocketManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/websocket_manager.py"
        DatabaseManager["DatabaseManager"]:::manager
        click DatabaseManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/database_manager.py"
        APIManager["APIManager"]:::manager
        click APIManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/api_manager.py"
        BanManager["BanManager"]:::manager
        click BanManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/ban_manager.py"
        MuteManager["MuteManager"]:::manager
        click MuteManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/mute_manager.py"
        PermissionManager["PermissionManager"]:::manager
        click PermissionManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/permission_manager.py"
        PartyManager["PartyManager"]:::manager
        click PartyManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/party_manager.py"
        QueueProcessor["QueueProcessor"]:::manager
        click QueueProcessor "https://github.com/deyoyk/rankedbedwars/blob/main/managers/queue_processor.py"
        StrikesManager["StrikesManager"]:::manager
        click StrikesManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/strikes_manager.py"
        ScreenshareManager["ScreenshareManager"]:::manager
        click ScreenshareManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/screenshare_manager.py"
        WorkerManager["WorkerManager"]:::manager
        click WorkerManager "https://github.com/deyoyk/rankedbedwars/blob/main/managers/workermanager.py"
    end

    %% Command and Event Handlers
    subgraph "Handlers"
        direction TB
        Commands["Commands/"]:::handlers
        click Commands "https://github.com/deyoyk/rankedbedwars/tree/main/commands/"
        Events["Events/"]:::handlers
        click Events "https://github.com/deyoyk/rankedbedwars/tree/main/events/"
    end

    %% WebSocket Subsystem
    subgraph "WebSocket Handlers"
        direction TB
        WS_Game["game_handler"]:::handlers
        click WS_Game "https://github.com/deyoyk/rankedbedwars/blob/main/managers/websocket/handlers/game_handler.py"
        WS_Player["player_handler"]:::handlers
        click WS_Player "https://github.com/deyoyk/rankedbedwars/blob/main/managers/websocket/handlers/player_handler.py"
        WS_Queue["queue_handler"]:::handlers
        click WS_Queue "https://github.com/deyoyk/rankedbedwars/blob/main/managers/websocket/handlers/queue_handler.py"
        WS_Scoring["scoring_handler"]:::handlers
        click WS_Scoring "https://github.com/deyoyk/rankedbedwars/blob/main/managers/websocket/handlers/scoring_handler.py"
        WS_Screenshare["screenshare_handler"]:::handlers
        click WS_Screenshare "https://github.com/deyoyk/rankedbedwars/blob/main/managers/websocket/handlers/screenshare_handler.py"
        WS_Voice["voice_handler"]:::handlers
        click WS_Voice "https://github.com/deyoyk/rankedbedwars/blob/main/managers/websocket/handlers/voice_handler.py"
        WS_Models["message_models"]:::handlers
        click WS_Models "https://github.com/deyoyk/rankedbedwars/blob/main/managers/websocket/models/messages.py"
        WS_Callbacks["ws_callbacks"]:::handlers
        click WS_Callbacks "https://github.com/deyoyk/rankedbedwars/blob/main/managers/websocket/utils/callbacks.py"
        WS_Errors["ws_error_handler"]:::handlers
        click WS_Errors "https://github.com/deyoyk/rankedbedwars/blob/main/managers/websocket/utils/error_handler.py"
    end

    %% Actions and Business Logic
    subgraph "Actions"
        direction TB
        ActionsDir["actions/"]:::logic
        click ActionsDir "https://github.com/deyoyk/rankedbedwars/tree/main/actions/"
    end

    %% Utilities, Themes, Assets, Configs
    subgraph "Utilities & Assets"
        direction TB
        Utils["utils/"]:::utils
        click Utils "https://github.com/deyoyk/rankedbedwars/tree/main/utils/"
        Themes["themes/"]:::utils
        click Themes "https://github.com/deyoyk/rankedbedwars/tree/main/themes/"
        Assets["asserts/"]:::utils
        click Assets "https://github.com/deyoyk/rankedbedwars/tree/main/asserts/"
        Configs["configs/"]:::configs
        click Configs "https://github.com/deyoyk/rankedbedwars/tree/main/configs/"
    end

    %% Dependency Files
    README["README.md"]:::configs
    click README "https://github.com/deyoyk/rankedbedwars/blob/main/README.md"
    Req["requirements.txt"]:::configs
    click Req "https://github.com/deyoyk/rankedbedwars/blob/main/requirements.txt"

    %% Connections
    Discord -->|gateway events| EventManager
    Discord -->|slash/prefix| CommandManager
    EventManager -->|routes to| Events
    CommandManager -->|invokes| Commands
    Commands -->|calls| EventManager
    Commands -->|uses| DatabaseManager
    Events -->|triggers| QueueProcessor
    Webhook -->|game_events| WebSocketManager
    WebSocketManager -->|dispatches| WS_Game
    WebSocketManager -->|dispatches| WS_Player
    WebSocketManager -->|dispatches| WS_Queue
    WebSocketManager -->|dispatches| WS_Scoring
    WebSocketManager -->|dispatches| WS_Screenshare
    WebSocketManager -->|dispatches| WS_Voice
    WS_* -->|business logic| ActionsDir
    ActionsDir -->|read/write| DatabaseManager
    DatabaseManager -->|persist| MongoDB
    APIManager -->|external calls| Discord
    Manager_Utils[Managers] -->|helper| Utils
    Manager_Utils -->|styles| Themes

    %% Styles
    classDef external fill:#D0E6FF,stroke:#4C97FF,color:#000
    classDef core fill:#E8F5E9,stroke:#43A047,color:#000
    classDef manager fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef handlers fill:#FFF9C4,stroke:#FBC02D,color:#000
    classDef logic fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef utils fill:#ECEFF1,stroke:#607D8B,color:#000
    classDef configs fill:#F3E5F5,stroke:#8E24AA,color:#000
```
