# e-psi-lon/epsi-bot architecture

> Architecture diagram of the GitHub repository e-psi-lon/epsi-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/e-psi-lon/epsi-bot
- Repository: https://github.com/e-psi-lon/epsi-bot

## Overview

##### Main Components
- Discord Bot Core: Represented by the main.py and its associated “cogs” (admin.py, channel.py, listeners.py, others.py, playlist.py, queue_related.py, state.py, todo.py). Each cog encapsulates a dedicated part of the bot’s functionality (e.g., administration, playlist management, queue handling).
- Web Panel: Located in the “panel” directory with a dedicated panel.py (the backend for the panel), HTML templates (index.html, panel.html, server.html), and static assets (style.css). This component is used for web-based management and monitoring of the bot.
- Database Layer: Although the database file itself (database.db) isn’t in the repo, the README explains its schema. This SQLite3 database holds all the dynamic data (servers, songs, playlists, queues, and user info).
- Utility Modules: Found in the “utils” directory (config.py, async_.py, panel.py, type_.py, utils.py) that provide helper functions for configuration management, asynchronous operations, type handling, etc.
- External Tools/Dependencies: For example, the “bin” folder contains ffmpeg.exe, which is likely used for audio processing. Additionally, external libraries and dependencies are declared in requirements.txt.
- Supplementary Scripts: The “_others” directory contains scripts like check_db.py and generate_db.py to help manage the database setup and validation.

##### Relationships and Interactions
- The Bot Core (main entry point at main.py) initializes and loads each cog module to provide commands and event listeners. Each cog might interact with the database and utility functions.
- The Web Panel operates as a separate service (within the same application) that provides management interfaces to control or monitor the bot. It uses its own endpoints (provided by panel.py) and renders templates, yet it also interacts with the database to display or update the bot’s state.
- Both the Bot Core and the Web Panel share access to the database, ensuring that song, playlist, and server data are always current.
- Utility modules are shared across both the Bot and Panel, allowing a consistent configuration and common functionality (like async operations or shared type definitions).
- The external tool (ffmpeg.exe) is invoked by the bot during tasks such as processing audio streams.

##### Architectural Patterns and Design Principles
- Modularity via “cogs”: Using the Discord.py cog system breaks the bot’s code into self-contained modules, making it easier to manage and extend.
- Separation of Concerns: The design clearly separates the Discord client (which processes commands and interacts with Discord’s API) from the web panel (which provides a UI) and from the database management.
- Utility Abstraction: The “utils” directory encapsulates common functionalities, reducing redundancy and improving maintainability.
- Lightweight Database: Utilizing SQLite for persistence simplifies deployment and enables quick setups without additional database servers.

##### Elements
- Bot core vs. web panel components.
- Database (as a storage service).
- External tools and utilities.
- Different types of interactions (e.g., synchronous command processing versus asynchronous web requests).

##### Final Advice
- Further decompose the Bot into its key modular parts (the various cogs) and the supporting utilities.
- Be detailed—if possible, include each cog module (perhaps grouped as similar functionality) to reflect the internal architecture.
- Interactions, especially the shared database and external dependency (ffmpeg), are clearly depicted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Discord Bot Core"
        MAIN["main.py"]:::discord
        subgraph "Cogs"
            ADMIN["admin.py"]:::discord
            CHANNEL["channel.py"]:::discord
            LISTENERS["listeners.py"]:::discord
            OTHERS["others.py"]:::discord
            PLAYLIST["playlist.py"]:::discord
            QUEUE["queue_related.py"]:::discord
            STATE["state.py"]:::discord
            TODO["todo.py"]:::discord
        end
    end

    subgraph "Web Panel"
        PANEL_BACKEND["panel.py"]:::web
        TEMPLATES["HTML Templates"]:::web
        STATIC["Static Assets (style.css)"]:::web
    end

    subgraph "Utility Modules"
        CONFIG["config.py"]:::util
        ASYNC_MODULE["async_.py"]:::util
        PANEL_UTIL["panel.py (utils)"]:::util
        TYPE_MODULE["type_.py"]:::util
        UTILS_MOD["utils.py"]:::util
    end

    DB["SQLite Database"]:::db

    EXT["ffmpeg.exe"]:::external

    subgraph "Supplementary Scripts"
        CHECK_DB["check_db.py"]:::supp
        GENERATE_DB["generate_db.py"]:::supp
    end

    EXTERNAL_DEPS["requirements.txt"]:::external

    %% Relationships for Discord Bot Core
    MAIN -->|"loads"| ADMIN
    MAIN -->|"loads"| CHANNEL
    MAIN -->|"loads"| LISTENERS
    MAIN -->|"loads"| OTHERS
    MAIN -->|"loads"| PLAYLIST
    MAIN -->|"loads"| QUEUE
    MAIN -->|"loads"| STATE
    MAIN -->|"loads"| TODO

    %% Bot Core using Utilities and External Tools
    MAIN -->|"uses"| CONFIG
    MAIN -->|"calls"| EXT

    ADMIN -->|"uses"| CONFIG
    CHANNEL -->|"uses"| ASYNC_MODULE
    LISTENERS -->|"uses"| TYPE_MODULE
    OTHERS -->|"uses"| UTILS_MOD
    PLAYLIST -->|"uses"| PANEL_UTIL
    QUEUE -->|"uses"| ASYNC_MODULE
    STATE -->|"uses"| TYPE_MODULE
    TODO -->|"uses"| UTILS_MOD

    %% Both Bot Core and Web Panel access the Database
    MAIN -->|"accesses"| DB
    PANEL_BACKEND -->|"accesses"| DB
    CONFIG -->|"accesses"| DB
    ASYNC_MODULE -->|"accesses"| DB

    %% Web Panel internal relationships
    PANEL_BACKEND -->|"renders"| TEMPLATES
    PANEL_BACKEND -->|"renders"| STATIC
    PANEL_BACKEND -->|"uses"| CONFIG

    %% External Dependencies supporting Bot and Panel
    EXTERNAL_DEPS -->|"requiredBy"| MAIN
    EXTERNAL_DEPS -->|"requiredBy"| PANEL_BACKEND

    %% Supplementary Scripts manage the Database
    CHECK_DB -->|"manages"| DB
    GENERATE_DB -->|"manages"| DB

    %% Shared Utilities services
    CONFIG ---|"shared"| ASYNC_MODULE
    CONFIG ---|"shared"| PANEL_UTIL
    CONFIG ---|"shared"| TYPE_MODULE
    CONFIG ---|"shared"| UTILS_MOD

    %% Click Events for Discord Bot Core
    click MAIN "https://github.com/e-psi-lon/epsi-bot/blob/main/main.py"
    click ADMIN "https://github.com/e-psi-lon/epsi-bot/blob/main/cogs/admin.py"
    click CHANNEL "https://github.com/e-psi-lon/epsi-bot/blob/main/cogs/channel.py"
    click LISTENERS "https://github.com/e-psi-lon/epsi-bot/blob/main/cogs/listeners.py"
    click OTHERS "https://github.com/e-psi-lon/epsi-bot/blob/main/cogs/others.py"
    click PLAYLIST "https://github.com/e-psi-lon/epsi-bot/blob/main/cogs/playlist.py"
    click QUEUE "https://github.com/e-psi-lon/epsi-bot/blob/main/cogs/queue_related.py"
    click STATE "https://github.com/e-psi-lon/epsi-bot/blob/main/cogs/state.py"
    click TODO "https://github.com/e-psi-lon/epsi-bot/blob/main/cogs/todo.py"

    %% Click Events for Web Panel
    click PANEL_BACKEND "https://github.com/e-psi-lon/epsi-bot/blob/main/panel/panel.py"
    click TEMPLATES "https://github.com/e-psi-lon/epsi-bot/tree/main/panel/templates"
    click STATIC "https://github.com/e-psi-lon/epsi-bot/blob/main/panel/static/style.css"

    %% Click Events for Utility Modules
    click CONFIG "https://github.com/e-psi-lon/epsi-bot/blob/main/utils/config.py"
    click ASYNC_MODULE "https://github.com/e-psi-lon/epsi-bot/blob/main/utils/async_.py"
    click PANEL_UTIL "https://github.com/e-psi-lon/epsi-bot/blob/main/utils/panel.py"
    click TYPE_MODULE "https://github.com/e-psi-lon/epsi-bot/blob/main/utils/type_.py"
    click UTILS_MOD "https://github.com/e-psi-lon/epsi-bot/blob/main/utils/utils.py"

    %% Click Events for External Tools/Dependencies
    click EXT "https://github.com/e-psi-lon/epsi-bot/blob/main/bin/ffmpeg.exe"
    click EXTERNAL_DEPS "https://github.com/e-psi-lon/epsi-bot/blob/main/requirements.txt"

    %% Click Events for Supplementary Scripts
    click CHECK_DB "https://github.com/e-psi-lon/epsi-bot/blob/main/_others/check_db.py"
    click GENERATE_DB "https://github.com/e-psi-lon/epsi-bot/blob/main/_others/generate_db.py"

    %% Styles
    classDef discord fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef web fill:#A9DFBF,stroke:#1D8348,stroke-width:2px;
    classDef util fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef db fill:#F5CBA7,stroke:#943126,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef supp fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
