# exceptedprism3/hitradio architecture

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

- Interactive diagram: https://gitdiagram.com/exceptedprism3/hitradio
- Repository: https://github.com/exceptedprism3/hitradio

## Overview

##### Project type and purpose
- HitRadio is a single-process Node.js Discord bot built with Discord.js.
- Purpose: connect to the HitRadio streaming endpoint and relay continuous music into Discord voice channels, while handling slash‐commands and basic state (e.g., uptime, votes).

##### File structure
- Entry point: `hitradio.js`
- Configuration: `config.json`, `.env` (DISCORD_TOKEN)
- Core logic split into:
- `loaders/` – modules that bootstrap the bot (commandLoader, eventLoader)
- `commands/` – each slash‐command implementation (play.js, leave.js, etc.)
- `events/` – event handlers (ready.js)
- `utils/` – shared services (database.js, logger.js, player.js)
- Previews folder holds assets (banner GIF), not part of runtime.
- Package files manage dependencies (Discord.js, any database or streaming libraries).

##### README for additional insights
- Features: 24/7 streaming, interactive buttons, rotating status messages, auto-join voice channel.
- Uses external streaming URL (HitRadio station) and Discord API (Gateway & REST).

a. Main components
- Discord Gateway & REST API
- Bot Application (Node.js process)
– Entry Point (`hitradio.js`)
– Loaders (`commandLoader`, `eventLoader`)
– Command Handlers (`/play`, `/leave`, etc.)
– Event Handlers (`ready`, others)
– Utilities (`player`, `database`, `logger`)
- External Streaming Service (HitRadio stream URL)
- Persistent Storage (as exposed by `utils/database.js`)
b. Relationships & interactions
- On start: `hitradio.js` reads `config.json` + `.env`, initializes client.
- Loaders register commands with Discord REST and attach event handlers to the Gateway.
- User issues slash command → Discord Gateway forwards the event → relevant command module runs → may call `player.js` to open a voice connection.
- `player.js` pulls raw audio from the external streaming URL and pipes it into Discord voice channel via Discord.js.
- `database.js` is called by commands/events to store or retrieve bot state (e.g., votes, uptime).
- `logger.js` captures runtime events/errors to console or log store.
c. Architectural patterns & principles
- Modular separation: command handlers, event handlers, and utilities are decoupled.
- Single responsibility: each utility or module has a focused job (e.g., audio streaming vs. DB operations).
- Layered bootstrapping: entry point → loaders → handlers.
d. Key technologies
- Node.js runtime
- Discord.js library (Gateway + REST + Voice)
- Any streaming library inside `utils/player.js` (e.g., prism-media or built-in stream)
- Chosen persistence layer (SQLite, JSON file, etc.) abstracted by `utils/database.js`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Discord["Discord Gateway & REST API"]:::external
    Stream["External HitRadio Stream Service"]:::external

    %% Bot Application
    subgraph "HitRadio Bot (Node.js)"
        direction TB
        Config["Configuration\nconfig.json & .env"]:::config
        Entry["Entry Point\nhitradio.js"]:::core

        subgraph "Loaders"
            direction TB
            CL["commandLoader.js"]:::core
            EL["eventLoader.js"]:::core
        end

        subgraph "Command Handlers"
            direction TB
            Help["help.js"]:::core
            Info["info.js"]:::core
            Leave["leave.js"]:::core
            Ping["ping.js"]:::core
            Play["play.js"]:::core
            Uptime["uptime.js"]:::core
            Vote["vote.js"]:::core
        end

        subgraph "Event Handlers"
            direction TB
            Ready["ready.js"]:::core
        end

        subgraph "Utilities"
            direction TB
            Database["database.js"]:::util
            Logger["logger.js"]:::util
            Player["player.js"]:::util
        end
    end

    %% Persistent Storage
    Storage["Persistent Storage"]:::external

    %% Boot Sequence & Config Loading
    Config -.->|"load config"| Entry
    Entry -->|"initialize loaders"| CL
    Entry -->|"initialize loaders"| EL

    %% Register and Attach
    CL -->|"register commands"| Discord
    EL -->|"attach event handlers"| Discord

    %% Event and Command Flows
    Discord -->|"slash command payload"| Help
    Discord -->|"slash command payload"| Info
    Discord -->|"slash command payload"| Leave
    Discord -->|"slash command payload"| Ping
    Discord -->|"slash command payload"| Play
    Discord -->|"slash command payload"| Uptime
    Discord -->|"slash command payload"| Vote

    Discord -->|"ready event"| Ready

    %% Command Interactions
    Play -->|"invoke streaming"| Player
    Player -->|"fetch audio stream"| Stream
    Player -->|"send audio frames"| Discord

    Info -->|"state read/write"| Database
    Uptime -->|"state read/write"| Database
    Vote -->|"state read/write"| Database

    %% Utilities Logging
    Ready -->|"log event"| Logger
    Play -->|"log playback"| Logger
    Info -->|"log query"| Logger

    %% DB Persistence
    Database -->|"persist data"| Storage

    %% Click Events
    click Entry "https://github.com/exceptedprism3/hitradio/blob/master/hitradio.js"
    click Config "https://github.com/exceptedprism3/hitradio/blob/master/config.json"
    click CL "https://github.com/exceptedprism3/hitradio/blob/master/loaders/commandLoader.js"
    click EL "https://github.com/exceptedprism3/hitradio/blob/master/loaders/eventLoader.js"
    click Help "https://github.com/exceptedprism3/hitradio/blob/master/commands/help.js"
    click Info "https://github.com/exceptedprism3/hitradio/blob/master/commands/info.js"
    click Leave "https://github.com/exceptedprism3/hitradio/blob/master/commands/leave.js"
    click Ping "https://github.com/exceptedprism3/hitradio/blob/master/commands/ping.js"
    click Play "https://github.com/exceptedprism3/hitradio/blob/master/commands/play.js"
    click Uptime "https://github.com/exceptedprism3/hitradio/blob/master/commands/uptime.js"
    click Vote "https://github.com/exceptedprism3/hitradio/blob/master/commands/vote.js"
    click Ready "https://github.com/exceptedprism3/hitradio/blob/master/events/ready.js"
    click Database "https://github.com/exceptedprism3/hitradio/blob/master/utils/database.js"
    click Logger "https://github.com/exceptedprism3/hitradio/blob/master/utils/logger.js"
    click Player "https://github.com/exceptedprism3/hitradio/blob/master/utils/player.js"

    %% Styles
    classDef external fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef core fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20;
    classDef util fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef config fill:#e0e0e0,stroke:#757575,color:#212121,stroke-dasharray: 5 5
```
