# fantasybot-red/songbird-node architecture

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

- Interactive diagram: https://gitdiagram.com/fantasybot-red/songbird-node
- Repository: https://github.com/fantasybot-red/songbird-node

## Overview

##### Project Type and Purpose
- This is a backend service—a Discord audio bot written in Rust.
- It listens for audio‐play requests (originating from a Python client), uses FFmpeg to process audio, and streams it into Discord voice channels via the serenity-rs and songbird crates.

##### File Structure
- Cargo.toml + src/*.rs ⇒ single Rust binary crate.
- src/main.rs ⇒ bootstrapper: loads config, initializes serenity and songbird, registers event handlers.
- src/obj_event.rs ⇒ defines event objects (e.g., incoming “play” requests).
- src/task_support.rs ⇒ schedules long-running tasks (e.g., streaming loops).
- src/ffmpeg_support.rs ⇒ wraps FFmpeg invocations (spawning, piping PCM into songbird).
- config.json ⇒ bot token, connection parameters, other settings.

##### Extract Additional Insights from the README
- Core dependencies: serenity-rs, songbird, FFmpeg (external).
- A companion Python client issues commands over the network to this service (via HTTP or a custom protocol).

##### Main Components
a. Config Loader
b. Discord Gateway Client (serenity-rs)
c. Voice Connection Manager (songbird)
d. Event Handler (obj_event)
e. Task Scheduler (task_support)
f. FFmpeg Processor (ffmpeg_support)
g. External Python Client
h. External FFmpeg Binary
i. Discord Voice Channels (Discord API service)

##### Relationships and Interactions
1) On startup, main.rs reads config.json → initializes Serenity Discord client + Songbird voice manager.
2) Python client → sends “play” or “stop” requests over the network to the bot (HTTP/WebSocket).
3) Serenity Gateway receives request → invokes Event Handler (obj_event.rs).
4) Event Handler enqueues work in Task Scheduler.
5) Task Scheduler uses FFmpeg Processor to spawn the external ffmpeg binary (ffmpeg_support.rs).
6) FFmpeg outputs PCM/audio data into a streaming pipe → handed to Songbird voice connection → streamed into Discord voice channel.
7) Bot monitors tasks (e.g., end-of-stream) and cleans up.

##### Architectural Patterns and Design Principles
- Modular separation of concerns: configuration, event parsing, task orchestration, media processing.
- Asynchronous event‐driven design using serenity’s event loop and Songbird’s voice‐async API.
- External‐process integration: FFmpeg runs as a child process; IPC via standard I/O pipes.
- Single-binary microservice: all logic bundled in one Rust executable.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    PythonClient["Python Client"]:::external
    FFmpegBinary["FFmpeg Binary"]:::external
    DiscordAPI["Discord Voice Channel\n(Discord API)"]:::external

    %% Configuration
    ConfigLoader["Config Loader\n(config.json)"]:::config

    %% CI/CD
    CICD["CI/CD Workflow\n(.github/workflows/main.yml)"]:::ci

    %% Internal Rust Modules
    subgraph "Rust Bot Service"
        direction TB
        Bootstrapper["Bootstrapper & Initialization\n(src/main.rs)"]:::internal
        EventLoop["Serenity Gateway\n(Event Loop)"]:::internal
        EventHandler["Event Handler\n(obj_event.rs)"]:::internal
        TaskScheduler["Task Scheduler\n(task_support.rs)"]:::internal
        FFmpegSupport["FFmpeg Processor\n(ffmpeg_support.rs)"]:::internal
        SongbirdMgr["Voice Connection Manager\n(songbird)"]:::internal
    end

    %% Initialization Flow
    ConfigLoader -->|"loads config"| Bootstrapper
    Bootstrapper -->|"init serenity & songbird"| EventLoop
    Bootstrapper -->|"init serenity & songbird"| SongbirdMgr

    %% Audio Play Flow
    PythonClient -->|"JSON command\nHTTP/WebSocket"| EventLoop
    EventLoop -->|"invoke play event"| EventHandler
    EventHandler -->|"enqueue task"| TaskScheduler
    TaskScheduler -->|"spawn ffmpeg"| FFmpegSupport
    FFmpegSupport -->|"pipe PCM audio"| SongbirdMgr
    FFmpegBinary -->|"executes as child"| FFmpegSupport
    SongbirdMgr -->|"stream audio"| DiscordAPI
    SongbirdMgr -->|"monitor stream end"| TaskScheduler

    %% CI/CD Connection
    CICD -.->|“build pipeline”| Bootstrapper

    %% Click Events
    click ConfigLoader "https://github.com/fantasybot-red/songbird-node/blob/master/config.json"
    click Bootstrapper "https://github.com/fantasybot-red/songbird-node/blob/master/src/main.rs"
    click EventHandler "https://github.com/fantasybot-red/songbird-node/blob/master/src/obj_event.rs"
    click TaskScheduler "https://github.com/fantasybot-red/songbird-node/blob/master/src/task_support.rs"
    click FFmpegSupport "https://github.com/fantasybot-red/songbird-node/blob/master/src/ffmpeg_support.rs"
    click CICD "https://github.com/fantasybot-red/songbird-node/blob/master/.github/workflows/main.yml"

    %% Styles
    classDef internal fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1;
    classDef external fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef config fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef ci fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
```
