# stryp0/mio architecture

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

- Interactive diagram: https://gitdiagram.com/stryp0/mio
- Repository: https://github.com/stryp0/mio

## Overview

##### Project Type and Purpose
- This is a standalone Discord music bot (“Mio”) written in TypeScript.
- It listens for chat commands in Discord text channels, fetches or downloads audio from YouTube, maintains an in-memory song queue, and streams audio into Discord voice channels.

##### File Structure Analysis
- src/index.ts
- Entry point: initializes Discord client, loads .env config via ConfigHandler, and registers the MessageHandler.
- src/commands/*.ts
- One file per user command (play, pause, skip, queue, shuffle, etc.).
- Implements a Command Pattern: each command exports metadata (name, args) + an execute() function.
- src/handlers/*.ts
- CommandHandler: maps incoming messages to the correct command module.
- MessageHandler: listens to Discord “message” events, pre-processes them and delegates to CommandHandler.
- ConfigHandler: reads environment variables (.env) and exposes typed config.
- DownloadHandler: interfaces with YouTube Data API + ytdl-core to fetch audio streams / manage caching.
- PlaybackHandler: opens FFmpeg processes, connects to Discord voice, and pushes audio data.
- QueueHandler: in-memory queue management (add, remove, shuffle, list).
- MetaHandler: generates metadata for embeds (duration, title, thumbnail).
- UIHandler: builds and sends Discord embed messages (song info, queue previews).
- Configuration files:
- .env.example / .gitignore (secure tokens)
- tsconfig.json, package.json (build scripts, dependencies)

##### Architecture from README
- Uses Discord Bot Token & YouTube Data API Key.
- Core features: queue system, playlist support, embedded UI.

a. Main Components
- Discord Gateway (discord.js client)
- Bot Application (Node.js process)
- MessageHandler
- CommandHandler
- ConfigHandler
- DownloadHandler ↔ YouTube Data API
- QueueHandler
- PlaybackHandler ↔ FFmpeg
- UIHandler / MetaHandler
- External Services
- YouTube Data API (search, metadata)
- YouTube audio streams (via ytdl-core)
- Discord Voice Server (for audio streaming)
b. Relationships & Data Flow
1. User types `!play <url>` → Discord Gateway emits “messageCreate”
2. MessageHandler parses prefix & passes command name + args to CommandHandler
3. CommandHandler invokes the corresponding command module
4. Command module requests DownloadHandler (for metadata or stream URL)
5. DownloadHandler calls YouTube Data API and/or ytdl-core, returns a readable audio stream
6. Command module enqueues item via QueueHandler
7. PlaybackHandler pulls next stream from QueueHandler, spawns FFmpeg to transcode if needed
8. PlaybackHandler pipes PCM data into Discord Voice Connection
9. UIHandler/MetaHandler send embed updates to the text channel
c. Architectural Patterns & Principles
- Event-Driven: Discord events drive the whole flow
- Command Pattern: decouple command definition from invocation logic
- Single Responsibility: each Handler has a well-defined role
- In-Memory State: queue lives in process memory (could be externalized later)
d. Key Technologies
- Node.js + TypeScript
- discord.js library (Discord Gateway & Voice)
- ytdl-core (audio stream fetching)
- FFmpeg (audio decoding/transcoding)
- dotenv (ConfigHandler)
- YouTube Data API v3

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Entry
    User["User"]:::external -->|"!play, !pause etc."| Index["Entry Point\nsrc/index.ts"]:::handler
    click Index "https://github.com/stryp0/mio/blob/main/src/index.ts"

    %% Configuration
    ConfigHandler["ConfigHandler"]:::handler -->|reads| EnvExample[".env.example"]:::external
    click ConfigHandler "https://github.com/stryp0/mio/blob/main/src/handlers/ConfigHandler.ts"
    click EnvExample "https://github.com/stryp0/mio/blob/main/.env.example"

    %% Discord Gateway and Message Flow
    Index -->|initializes| Gateway["Discord Gateway\n(discord.js)"]:::event
    Gateway -->|"messageCreate event"| MessageHandler["MessageHandler"]:::handler
    click MessageHandler "https://github.com/stryp0/mio/blob/main/src/handlers/MessageHandler.ts"
    MessageHandler -->|"delegates command"| CommandHandler["CommandHandler"]:::handler
    click CommandHandler "https://github.com/stryp0/mio/blob/main/src/handlers/CommandHandler.ts"

    %% Commands Subgraph
    subgraph "Command Modules"
        direction TB
        Play["play"]:::handler
        Pause["pause"]:::handler
        Resume["resume"]:::handler
        Skip["skip"]:::handler
        Stop["stop"]:::handler
        QueueCmd["queue"]:::handler
        PlayNext["playnext"]:::handler
        Playlist["playlist"]:::handler
        Shuffle["shuffle"]:::handler
        Remove["remove"]:::handler
        Clear["clear"]:::handler
        Move["move"]:::handler
        Search["search"]:::handler
        Help["help"]:::handler
    end
    click Play "https://github.com/stryp0/mio/blob/main/src/commands/play.ts"
    click Pause "https://github.com/stryp0/mio/blob/main/src/commands/pause.ts"
    click Resume "https://github.com/stryp0/mio/blob/main/src/commands/resume.ts"
    click Skip "https://github.com/stryp0/mio/blob/main/src/commands/skip.ts"
    click Stop "https://github.com/stryp0/mio/blob/main/src/commands/stop.ts"
    click QueueCmd "https://github.com/stryp0/mio/blob/main/src/commands/queue.ts"
    click PlayNext "https://github.com/stryp0/mio/blob/main/src/commands/playnext.ts"
    click Playlist "https://github.com/stryp0/mio/blob/main/src/commands/playlist.ts"
    click Shuffle "https://github.com/stryp0/mio/blob/main/src/commands/shuffle.ts"
    click Remove "https://github.com/stryp0/mio/blob/main/src/commands/remove.ts"
    click Clear "https://github.com/stryp0/mio/blob/main/src/commands/clear.ts"
    click Move "https://github.com/stryp0/mio/blob/main/src/commands/move.ts"
    click Search "https://github.com/stryp0/mio/blob/main/src/commands/search.ts"
    click Help "https://github.com/stryp0/mio/blob/main/src/commands/help.ts"

    CommandHandler -->|invokes| Play
    CommandHandler -->|invokes| Pause
    CommandHandler -->|invokes| Resume
    CommandHandler -->|invokes| Skip
    CommandHandler -->|invokes| Stop
    CommandHandler -->|invokes| QueueCmd
    CommandHandler -->|invokes| PlayNext
    CommandHandler -->|invokes| Playlist
    CommandHandler -->|invokes| Shuffle
    CommandHandler -->|invokes| Remove
    CommandHandler -->|invokes| Clear
    CommandHandler -->|invokes| Move
    CommandHandler -->|invokes| Search
    CommandHandler -->|invokes| Help

    %% Download and Queue
    DownloadHandler["DownloadHandler"]:::handler -->|"search/metadata"| YouTubeAPI["YouTube Data API"]:::external
    DownloadHandler -->|"audio stream"| YTDL["ytdl-core"]:::external
    click DownloadHandler "https://github.com/stryp0/mio/blob/main/src/handlers/DownloadHandler.ts"
    CommandHandler -->|requests download| DownloadHandler

    QueueHandler["QueueHandler"]:::handler -->|holds songs| QueueStore["In-Memory Queue"]:::data
    click QueueHandler "https://github.com/stryp0/mio/blob/main/src/handlers/QueueHandler.ts"
    Play -->|"enqueue"| QueueHandler
    Pause -->|"pause queue"| QueueHandler
    Skip -->|"skip item"| QueueHandler

    %% Playback Pipeline
    PlaybackHandler["PlaybackHandler"]:::handler -->|spawns| FFmpeg["FFmpeg"]:::external
    PlaybackHandler -->|"streams PCM audio"| Voice["Discord Voice Server"]:::external
    click PlaybackHandler "https://github.com/stryp0/mio/blob/main/src/handlers/PlaybackHandler.ts"
    QueueHandler -->|provides next stream| PlaybackHandler
    DownloadHandler ---|"raw audio stream"| PlaybackHandler

    %% UI and Metadata
    MetaHandler["MetaHandler"]:::handler -->|builds metadata| UIHandler["UIHandler"]:::handler
    click MetaHandler "https://github.com/stryp0/mio/blob/main/src/handlers/MetaHandler.ts"
    click UIHandler "https://github.com/stryp0/mio/blob/main/src/handlers/UIHandler.ts"
    UIHandler -->|sends embed| Gateway

    %% Project Config Files
    subgraph "Project Config"
        TSConfig["tsconfig.json"]:::external
        Package["package.json"]:::external
        Gitignore[".gitignore"]:::external
        Readme["README.md"]:::external
    end

    %% Styles
    classDef event fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef handler fill:#E0FFFF,stroke:#000,stroke-width:1px;
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px;
```
