# utlandr/mksbot architecture

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

- Interactive diagram: https://gitdiagram.com/utlandr/mksbot
- Repository: https://github.com/utlandr/mksbot

## Overview

##### Project Type and Purpose
- MksBot is a single‐process, asynchronous Discord bot written in Python.
- It uses discord.py’s rewrite branch (v1.0+), implements a plugin (Cog) architecture, and interacts with external services (YouTube, Reddit) and local audio files.

##### File Structure
- Top‐level files:
- mksbot_main.py – the entry point (bootstraps bot, loads Cogs, reads config)
- base_functions.py – shared utility routines
- config-template.yaml – configuration schema (token, prefixes, API keys)
- requirements.txt – Python dependencies
- audio/ – local WAV files for text‐to‐speech “Droidspeak” and an output/ directory
- cogs/ – three subdirectories for plugin modules:
- amusement/ – fun commands
- reddit/ – PRAW-based web scraping
- voice/ – audio streaming and TTS, plus voice_config.yml
- testing/ – contains simple timing test script
- screenshots/ – documentation assets

##### README for Technical Insights
- The bot streams YouTube/local audio (ffmpeg), scrapes Reddit (PRAW), handles commands via cogs, and runs on a Raspberry Pi.
- Dependencies: discord.py (rewrite), ffmpeg, reddit modules.

##### Detail Level
- Config loader feeding into mksbot_main.
- Two distinct media‐streaming flows.
- Avoid over­crowding: group minor utilities if needed, but keep the core/event flow fully detailed.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Environment
    Host["Raspberry Pi / Server"]:::external

    %% Core Application
    subgraph "Core"
        Main["mksbot_main.py"]:::core
        Config["config-template.yaml"]:::core
        Utils["base_functions.py"]:::core
        Req["requirements.txt"]:::core
    end

    %% Async Event Loop & Dispatcher
    EventLoop["Async Event Loop\n(asyncio reactor)"]:::core
    Dispatcher["Command Dispatcher\n(discord.py core)"]:::core

    %% Cogs (Plugins)
    subgraph "Cogs"
        subgraph "Amusement Cog" 
            AmuseMain["amusement.py"]:::plugin
            AmuseFun["amusement_fun.py"]:::plugin
        end
        subgraph "Reddit Cog"
            RedditMain["reddit.py"]:::plugin
            RedditFun["reddit_fun.py"]:::plugin
        end
        subgraph "Voice Cog"
            VoiceMain["voice.py"]:::plugin
            VoiceFun["voice_fun.py"]:::plugin
            Streamable["streamable.py"]:::plugin
            VoiceConfig["voice_config.yml"]:::core
        end
    end

    %% Media Subsystem
    subgraph "Media Pipeline"
        AudioRepo["audio/droid_speak_audio/"]:::media
        AudioOut["audio/output/"]:::media
        TempoAdj["audio/tempo_adj.sh"]:::media
        FFmpeg["ffmpeg process"]:::media
        YouTubeDL["YouTube Extraction\n(youtube_dl)"]:::media
    end

    %% External Services
    subgraph "External Services"
        DiscordGateway["Discord Gateway\n(WebSocket & REST)"]:::external
        RedditAPI["Reddit API\n(PRAW)"]:::external
        YouTubeService["YouTube"]:::external
    end

    %% Documentation & Testing
    Docs["screenshots/"]:::core
    Test["testing/timing.py"]:::core

    %% Relationships
    Host --> Main
    Main -->|loads| Config
    Main -->|imports| Utils
    Main -->|install deps| Req
    Main --> EventLoop
    EventLoop --> Dispatcher
    Dispatcher --> AmuseMain
    Dispatcher --> RedditMain
    Dispatcher --> VoiceMain

    Utils --> AmuseMain
    Utils --> RedditMain
    Utils --> VoiceMain

    VoiceMain -->|reads| VoiceConfig
    VoiceMain --> AudioRepo
    VoiceMain --> YouTubeDL
    AudioRepo --> FFmpeg
    YouTubeDL --> FFmpeg
    FFmpeg -->|voice stream| DiscordGateway

    RedditMain -->|PRAW queries| RedditAPI
    RedditAPI -->|data| RedditMain
    RedditMain -->|formats| Utils
    RedditMain -->|posts| DiscordGateway

    AmuseMain -->|access| AudioRepo
    AmuseFun -->|uses| Utils
    AmuseMain -->|responds via| DiscordGateway

    Main --> Docs
    Main --> Test

    EventLoop -->|events| DiscordGateway
    Dispatcher -->|dispatch| EventLoop

    %% Legend
    classDef core fill:#d0f0c0,stroke:#333,stroke-width:1px
    classDef plugin fill:#c0d0f0,stroke:#333,stroke-width:1px
    classDef external fill:#f0c0d0,stroke:#333,stroke-width:1px
    classDef media fill:#f0e68c,stroke:#333,stroke-width:1px

    %% Click Events
    click Main "https://github.com/utlandr/mksbot/blob/master/mksbot_main.py"
    click Utils "https://github.com/utlandr/mksbot/blob/master/base_functions.py"
    click Config "https://github.com/utlandr/mksbot/blob/master/config-template.yaml"
    click AmuseMain "https://github.com/utlandr/mksbot/blob/master/cogs/amusement/amusement.py"
    click AmuseFun "https://github.com/utlandr/mksbot/blob/master/cogs/amusement/amusement_fun.py"
    click RedditMain "https://github.com/utlandr/mksbot/blob/master/cogs/reddit/reddit.py"
    click RedditFun "https://github.com/utlandr/mksbot/blob/master/cogs/reddit/reddit_fun.py"
    click VoiceMain "https://github.com/utlandr/mksbot/blob/master/cogs/voice/voice.py"
    click VoiceFun "https://github.com/utlandr/mksbot/blob/master/cogs/voice/voice_fun.py"
    click Streamable "https://github.com/utlandr/mksbot/blob/master/cogs/voice/streamable.py"
    click VoiceConfig "https://github.com/utlandr/mksbot/blob/master/cogs/voice/voice_config.yml"
    click AudioRepo "https://github.com/utlandr/mksbot/tree/master/audio/droid_speak_audio/"
    click AudioOut "https://github.com/utlandr/mksbot/tree/master/audio/output/"
    click TempoAdj "https://github.com/utlandr/mksbot/blob/master/audio/tempo_adj.sh"
    click Req "https://github.com/utlandr/mksbot/blob/master/requirements.txt"
    click Test "https://github.com/utlandr/mksbot/blob/master/testing/timing.py"
    click Docs "https://github.com/utlandr/mksbot/tree/master/screenshots/"
```
