# cog-creators/red-discordbot architecture

> Architecture diagram of the GitHub repository cog-creators/red-discordbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cog-creators/red-discordbot
- Repository: https://github.com/cog-creators/red-discordbot

## Overview

##### Project Type and Purpose
- This is a self-hosted, fully modular Discord bot written in Python.
- It’s built on discord.py and exposes an event-driven core that dynamically loads “cogs” (plugins) to provide features like moderation, music playback, trivia, stream alerts, economy, etc.
- Storage is abstracted via a driver layer supporting JSON, MongoDB, or PostgreSQL. Audio is offloaded to a Lavalink node, and various external APIs (YouTube, Spotify, Twitch, etc.) are called as needed.

##### File Structure Analysis
- Top level:
- README, setup, CI/config files (GitHub workflows, tox, Makefiles).
- `redbot/` – the main Python package.
- – `core/`: the engine (bot bootstrap, event loop, command parser, driver abstractions, i18n, RPC, data manager).
- – `cogs/`: each subfolder is a feature plugin (admin, audio, trivia, etc.), each with code, converters, event handlers, locales.
- – `vendored/`: third-party vendored libraries (discord-ext-menus).
- – `pytest/` & `tests/`: test support & unit tests.
- `requirements/`, `schema/`: dependency definitions and JSON schemas for cogs & config.
- Key patterns:
- Plugin (cog) architecture – cogs are discovered/loaded at runtime.
- Event-driven – Discord gateway events feed into core, dispatched to cogs.
- Adapter/driver pattern – core routes persistence calls through pluggable drivers.

##### README Insights
- Confirms modularity (enable/disable cogs), lists built-in modules, shows external plugin ecosystem.
- Mentions supported platforms and licensing.

a. Main Components
1. User (Discord users & administrators)
2. Discord API (Gateway & REST endpoints)
3. Red Bot Application
- Core Engine (bootstrapping, event loop, command parser)
- Cog Manager (discovers & loads plugin modules)
- Storage Driver Layer (JSON/Mongo/Postgres adapters)
- RPC & CLI Interfaces (for remote control & admin commands)
4. Plugins/Cogs (moderation, audio, trivia, economy, etc.)
5. Audio Subsystem
- Lavalink Node Manager (spawns/monitors Lavalink process)
- Lavalink Server (external or managed node)
6. External Services/APIs (YouTube, Spotify, Twitch, etc.)
7. Persistence Backends (local JSON files, MongoDB, PostgreSQL)

b. Relationships & Interactions
- Users send commands → Discord Gateway → Core Engine → Cog Manager dispatches to appropriate Cog → Cog may:
- Query/update data via Storage Driver → writes to JSON/Mongo/Postgres
- Call external APIs (e.g. YouTube search) → REST over HTTPS
- For audio Cogs: send playback commands to Lavalink Node → audio over WebSocket
- Emit events back to Core → Core posts messages via Discord REST API
- CLI/RPC layer connects to Core for administrative automation.

c. Architectural Patterns & Principles
- Plugin/Extension Pattern: each Cog implements a common interface for commands & events.
- Adapter Pattern: Storage drivers adhere to a uniform interface, enabling swapping backends.
- Event-Driven Architecture: incoming Discord events are broadcast to subscribers (cogs).
- Separation of Concerns: Core handles orchestration; Cogs encapsulate features; Drivers abstract persistence; Audio handled via separate process.

d. Key Technologies & Frameworks
- Python 3.x, discord.py
- Lavalink (audio), WebSocket connections
- Storage drivers: JSON (filesystem), PyMongo (MongoDB), psycopg2 (PostgreSQL)
- i18n via gettext (.po files included with cogs & core)
- CI: GitHub Actions, tox; Documentation: Sphinx (docs/)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Users and Discord API
    User["Discord User"]:::external
    DiscordAPI["Discord API\n(Gateway & REST)"]:::external

    User -->|"sends command"| DiscordAPI
    DiscordAPI -->|"event stream"| CoreEngine

    %% Core Engine Subgraph
    subgraph "Core Engine" 
        direction TB
        Boot["Bootstrap (__main__.py)"]:::core
        BotCore["Bot Core (bot.py)"]:::core
        Events["Event Loop (_events.py)"]:::core
        CmdParser["Command Parser\n(commands.py & context.py)"]:::core
        CogMgr["Cog Manager (_cog_manager.py)"]:::core
        DataMgr["Data Manager\ndata_manager.py"]:::core
        Config["Configuration\n(config.py & _settings_caches.py)"]:::core
        I18n["Internationalization\n(i18n.py & locales)"]:::core
        RPC["RPC Interface\n(_rpc.py)"]:::core
        CLI["CLI Interface\n(_cli.py)"]:::core
        DevCmd["Dev Commands\ndev_commands.py"]:::core
    end

    %% Core to Discord
    CoreEngine--- DiscordAPI
    Boot --> BotCore --> Events --> CmdParser --> CogMgr
    CogMgr --> DataMgr
    DataMgr --> Drivers
    Config --> DataMgr
    I18n --> CmdParser
    RPC --> BotCore
    CLI --> BotCore
    DevCmd --> BotCore

    %% Drivers Subgraph
    subgraph "Storage Driver Layer"
        direction TB
        BaseDrv["Base Driver\n(base.py)"]:::persistence
        JSONDrv["JSON Driver\n(json.py)"]:::persistence
        MongoDrv["Mongo Driver\n(_mongo.py)"]:::persistence
        PgDrv["Postgres Driver\n(postgres.py)"]:::persistence
    end

    Drivers --> BaseDrv
    BaseDrv --> JSONDrv
    BaseDrv --> MongoDrv
    BaseDrv --> PgDrv

    %% Datastores
    subgraph "Persistence Backends"
        direction TB
        JSONDB[/"File Storage (JSON)"/]:::persistence
        MongoDB[(MongoDB)]:::persistence
        Postgres[(PostgreSQL)]:::persistence
    end

    JSONDrv -->|"reads/writes"| JSONDB
    MongoDrv -->|"reads/writes"| MongoDB
    PgDrv -->|"reads/writes"| Postgres

    %% Plugin Layer
    subgraph "Plugin / Cog Layer" 
        direction TB
        CogsFolder["All Cogs (redbot/cogs/)"]:::plugin
        Moderation["Moderation Cog\n(mod/mod.py & events.py)"]:::plugin
        AudioCog["Audio Cog\n(audio_dataclasses.py,\nplaylists.py, events)"]:::plugin
        Economy["Economy Cog\neconomy.py"]:::plugin
        Trivia["Trivia Cog\ntrivia.py & data"]:::plugin
        Vendored["Vendored Libs\n(discord-ext-menus)"]:::plugin
    end

    CogMgr --> CogsFolder
    CogsFolder --> Moderation
    CogsFolder --> AudioCog
    CogsFolder --> Economy
    CogsFolder --> Trivia
    CogsFolder --> Vendored

    %% Audio Subsystem
    subgraph "Audio Subsystem"
        direction TB
        AudioMgr["Lavalink Node Manager\n(ll_server_config.py)"]:::core
        LavalinkServer["Lavalink Server"]:::external
        subgraph "Audio API Adapters"
            direction TB
            SPAPI["Spotify Adapter\nspotify.py"]:::external
            YTAPI["YouTube Adapter\nyoutube.py"]:::external
            APIIface["API Interface\ninterface.py"]:::external
        end
    end

    AudioCog --> AudioMgr
    AudioMgr --> LavalinkServer
    AudioCog --> SPAPI
    AudioCog --> YTAPI
    AudioCog --> APIIface

    %% External APIs
    subgraph "External Services"
        direction TB
        YouTube["YouTube"]:::external
        Spotify["Spotify"]:::external
        Twitch["Twitch"]:::external
    end

    SPAPI -->|"REST|HTTPS"| Spotify
    YTAPI -->|"REST|HTTPS"| YouTube
    APIIface -->|"REST|HTTPS"| Twitch

    %% Click Events
    click Boot "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/__main__.py"
    click BotCore "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/bot.py"
    click Events "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/_events.py"
    click CmdParser "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/commands/commands.py"
    click CmdParser "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/commands/context.py"
    click CogMgr "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/_cog_manager.py"
    click DataMgr "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/data_manager.py"
    click Config "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/config.py"
    click I18n "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/i18n.py"
    click RPC "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/_rpc.py"
    click CLI "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/_cli.py"
    click DevCmd "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/dev_commands.py"
    click BaseDrv "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/_drivers/base.py"
    click JSONDrv "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/_drivers/json.py"
    click MongoDrv "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/_drivers/_mongo.py"
    click PgDrv "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/core/_drivers/postgres/postgres.py"
    click CogsFolder "https://github.com/cog-creators/red-discordbot/tree/V3/develop/redbot/cogs/"
    click Moderation "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/cogs/mod/mod.py"
    click AudioCog "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/cogs/audio/manager.py"
    click SPAPI "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/cogs/audio/apis/spotify.py"
    click YTAPI "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/cogs/audio/apis/youtube.py"
    click APIIface "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/cogs/audio/apis/interface.py"
    click AudioMgr "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/cogs/audio/managed_node/ll_server_config.py"
    click Economy "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/cogs/economy/economy.py"
    click Trivia "https://github.com/cog-creators/red-discordbot/blob/V3/develop/redbot/cogs/trivia/trivia.py"
    click Vendored "https://github.com/cog-creators/red-discordbot/tree/V3/develop/redbot/vendored/discord-ext-menus/"
    click JSONDB "https://github.com/cog-creators/red-discordbot/tree/V3/develop/schema/"
    classDef core fill:#D6E9FE,stroke:#3178C6,stroke-width:2px
    classDef plugin fill:#D4F4DD,stroke:#33A852,stroke-width:2px
    classDef persistence fill:#FFE5B4,stroke:#E08E00,stroke-width:2px
    classDef external fill:#F8D7DA,stroke:#D9534F,stroke-width:2px
```
