# lowlevelsubmarine/tronic architecture

> Architecture diagram of the GitHub repository lowlevelsubmarine/tronic, 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/lowlevelsubmarine/tronic
- Repository: https://github.com/lowlevelsubmarine/tronic

## Overview

##### Project type and purpose
- Tronic is a backend‐only, event‐driven Discord bot written in Java (with a gradual migration to Kotlin).
- It connects to the Discord Gateway via JDA, listens for user events (messages, button clicks, voice updates), processes commands and button interactions, manages a music queue (YouTube, Spotify, etc.), persists state per guild/user, and logs events.

##### File structure
- Top‐level: Gradle build files, CI/CD workflows (.github), design assets (logos, mockups).
- src/main/java/com/tronic:
- actions, arguments – abstraction for request handlers and argument parsing
- bot/core – bootstrapping (ConfigProvider, Core, Tronic entrypoint, Updater)
- bot/commands & bot/buttons – command/button definitions, handlers, validators
- bot/listeners – JDA event listeners (message, button, voice updates, ready)
- bot/music – MusicManager, player abstractions, playlist/queue items
- bot/music/sources – TrackProvider implementations for LavaPlayer, YouTube, Spotify, URL, etc.
- bot/storage – JSON/Kotlin storage for guild/user settings
- bot/statistics – collecting and serializing usage stats
- bot/io, tools, logger – logging, utility classes, I/O wrappers
- src/test – unit tests for the logger

##### README for additional insights
- Simplicity, easy button controls, autocorrection, queueing various music sources.
- CI pipeline builds a fat JAR, configuration via JSON file, GPL v3 license.

##### Main components
a. Discord Gateway (JDA client)
b. Core Application
- Tronic (main)
- ConfigProvider & ReleaseConfig
- Updater (auto‐release)
c. Event Dispatch Layer
- Listeners (CommandListener, ButtonListener, VoiceUpdateListener, ReadyListener, etc.)
d. Processing Layer
- CommandHandler & Command classes
- ButtonHandler & Button classes
- Argument parsing (Argument, Arguments, type‐specific arguments)
- HyperchannelManager, ShortcutResolver, QuestionHandler
e. Service Layer
- MusicManager + Player + AudioPlayerSendHandler
- TrackProvider implementations (YouTube, Spotify, URL, LavaPlayer)
- StatisticsHandler + Serializer + GraphRenderer
f. Persistence Layer
- Storage interface + StorageGlue
- GuildStorage, UserStorage, StaticStorage (JSON‐backed)
g. Utilities and Logging
- Logger + TronicMessage
- Tools (FileUtils, GsonUtils, JDAUtils, Markdown, etc.)
h. External Services
- Discord API (Gateway, Voice WebSocket, REST API)
- YouTube/Spotify APIs or scraping libraries
i. CI/CD Pipeline
- GitHub Actions workflows, Dependabot integration

##### Relationships and data flow
- Discord Gateway emits events → Listeners pick up events → Dispatch to appropriate Handler (command or button) → Handler invokes Actions (business logic) → Actions coordinate with Service Layer (MusicManager, StatisticsHandler, Storage) → Responses sent back via JDA to Discord (messages, embeds, voice frames).
- TrackProviders fetch/stream audio from external APIs → Audio frames sent through AudioPlayerSendHandler into Discord voice connection.
- Updater checks GitHub tags/releases → triggers CI/CD to build and publish new JAR.

##### Architectural patterns and design principles
- Layered (Presentation/Event → Processing → Services → Persistence)
- Command Pattern for encapsulating each bot command
- Strategy Pattern for interchangeable TrackProvider implementations
- Observer/Event‐Driven via JDA Listeners
- Dependency Inversion: core classes depend on abstractions (Storage, TrackProvider interfaces)
- Single Responsibility: each package/folder has clearly delineated concern

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems" 
        direction TB
        DiscordAPI["Discord API\n(Gateway, REST, Voice)"]:::external
        YouTubeAPI["YouTube API / Scraper"]:::external
        SpotifyAPI["Spotify API / Scraper"]:::external
        GitHubCI["GitHub Actions\n(ci.yml, autoRelease.yml,\ndependamerge.yml)"]:::external
    end

    %% Core Application
    subgraph "Core Application" 
        direction TB
        TronicEntrypoint["Tronic\n(main)"]:::core
        ConfigProvider["ConfigProvider"]:::core
        ReleaseConfig["ReleaseConfig"]:::core
        Updater["Updater"]:::core
    end

    %% Event Dispatch Layer
    subgraph "Event Dispatch Layer" 
        direction TB
        CommandListener["CommandListener"]:::listeners
        ButtonListener["ButtonListener"]:::listeners
        VoiceUpdateListener["VoiceUpdateListener"]:::listeners
        ReadyListener["ReadyListener"]:::listeners
        OtherListeners["Other JDA Listeners"]:::listeners
    end

    %% Processing Layer
    subgraph "Processing Layer" 
        direction TB
        CommandHandler["CommandHandler"]:::processing
        CommandClass["Command"]:::processing
        ButtonHandler["ButtonHandler"]:::processing
        ButtonClass["Button"]:::processing
        ArgumentParsing["Arguments\n(Argument, Arguments)"]:::processing
        HyperchannelManager["HyperchannelManager"]:::processing
        ShortcutResolver["ShortcutResolver"]:::processing
        QuestionHandler["QuestionHandler"]:::processing
    end

    %% Service Layer
    subgraph "Service Layer" 
        direction TB
        MusicManager["MusicManager"]:::service
        Player["Player"]:::service
        AudioSendHandler["AudioPlayerSendHandler"]:::service
        TrackProviders["TrackProviders\n(YouTube, Spotify,\nURL, LavaPlayer)"]:::service
        StatisticsHandler["StatisticsHandler"]:::service
        StatisticsSerializer["StatisticsSerializer"]:::service
        StatisticsGraph["StatisticsGraphRenderer"]:::service
    end

    %% Persistence Layer
    subgraph "Persistence Layer" 
        direction TB
        StorageInterface["Storage"]:::persistence
        StorageGlue["StorageGlue"]:::persistence
        GuildStorage["GuildStorage"]:::persistence
        UserStorage["UserStorage"]:::persistence
        StaticStorage["StaticStorage"]:::persistence
    end

    %% Utilities and Logging
    subgraph "Utilities & Logging" 
        direction TB
        Logger["Logger"]:::utils
        TronicMessage["TronicMessage"]:::utils
        Tools["Tools\n(FileUtils, GsonUtils,\nJDAUtils, Markdown)"]:::utils
        CoreLogger["Core Logger\n(com.tronic.logger)"]:::utils
    end

    %% Runtime Flow
    DiscordAPI -->|"CommandEvent"| CommandListener
    DiscordAPI -->|"ButtonEvent"| ButtonListener
    DiscordAPI -->|"VoiceUpdate"| VoiceUpdateListener
    DiscordAPI -->|"ReadyEvent"| ReadyListener

    CommandListener -->|"dispatch"| CommandHandler
    ButtonListener -->|"dispatch"| ButtonHandler
    VoiceUpdateListener -->|"voice data"| AudioSendHandler
    ReadyListener -->|"init"| TronicEntrypoint

    CommandHandler -->|"execute"| CommandClass
    ButtonHandler -->|"execute"| ButtonClass
    CommandClass -->|"parse args"| ArgumentParsing
    ButtonClass -->|"validate"| ArgumentParsing

    CommandClass -->|"use"| HyperchannelManager
    CommandClass -->|"use"| ShortcutResolver
    CommandClass -->|"use"| QuestionHandler

    CommandHandler -->|"invoke"| MusicManager
    CommandHandler -->|"invoke"| StatisticsHandler
    ButtonHandler -->|"invoke"| StatisticsHandler

    MusicManager -->|"create player"| Player
    Player -->|"stream frames"| AudioSendHandler
    AudioSendHandler -->|"send audio"| DiscordAPI
    MusicManager -->|"fetch track"| TrackProviders
    TrackProviders -->|"API calls"| YouTubeAPI
    TrackProviders -->|"API calls"| SpotifyAPI

    StatisticsHandler -->|"serialize"| StatisticsSerializer
    StatisticsSerializer -->|"render"| StatisticsGraph
    StatisticsGraph -->|"output"| DiscordAPI

    CommandHandler -->|"persist"| StorageInterface
    StorageInterface -->|"glue"| StorageGlue
    StorageGlue --> GuildStorage
    StorageGlue --> UserStorage
    StorageGlue --> StaticStorage

    TronicEntrypoint --> ConfigProvider
    TronicEntrypoint --> ReleaseConfig
    TronicEntrypoint --> Updater
    Updater --> GitHubCI

    TronicEntrypoint --> Logger
    Logger --> TronicMessage
    CommandHandler --> Tools
    MusicManager --> Tools

    %% Click Events
    click DiscordAPI "https://github.com/lowlevelsubmarine/tronic/tree/master/src/main/java/com/tronic/bot/listeners"
    click TronicEntrypoint "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/core/Tronic.java"
    click ConfigProvider "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/core/ConfigProvider.java"
    click ReleaseConfig "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/ReleaseConfig.java"
    click Updater "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/core/Updater.java"
    click CommandListener "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/listeners/CommandListener.java"
    click ButtonListener "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/listeners/ButtonListener.java"
    click VoiceUpdateListener "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/listeners/VoiceUpdateListener.java"
    click ReadyListener "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/listeners/ReadyListener.java"
    click CommandHandler "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/commands/CommandHandler.java"
    click CommandClass "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/commands/Command.java"
    click ButtonHandler "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/buttons/ButtonHandler.java"
    click ButtonClass "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/buttons/Button.java"
    click ArgumentParsing "https://github.com/lowlevelsubmarine/tronic/tree/master/src/main/java/com/tronic/arguments"
    click HyperchannelManager "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/hyperchannel/HyperchannelManager.java"
    click ShortcutResolver "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/shortcuts/ShortcutResolver.java"
    click QuestionHandler "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/questions/QuestionHandler.java"
    click MusicManager "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/music/MusicManager.java"
    click Player "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/music/playing/Player.java"
    click AudioSendHandler "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/music/playing/AudioPlayerSendHandler.java"
    click TrackProviders "https://github.com/lowlevelsubmarine/tronic/tree/master/src/main/java/com/tronic/bot/music/sources/track_provider"
    click StatisticsHandler "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/stats/StatisticsHandler.java"
    click StatisticsSerializer "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/stats/StatisticsSerializer.java"
    click StatisticsGraph "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/stats/StatisticsGraphRenderer.java"
    click StorageInterface "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/storage/Storage.java"
    click StorageGlue "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/storage/StorageGlue.kt"
    click GuildStorage "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/storage/GuildStorage.kt"
    click UserStorage "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/storage/UserStorage.kt"
    click StaticStorage "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/storage/StaticStorage.kt"
    click Logger "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/io/Logger.java"
    click TronicMessage "https://github.com/lowlevelsubmarine/tronic/blob/master/src/main/java/com/tronic/bot/io/TronicMessage.java"
    click Tools "https://github.com/lowlevelsubmarine/tronic/tree/master/src/main/java/com/tronic/bot/tools"
    click CoreLogger "https://github.com/lowlevelsubmarine/tronic/tree/master/src/main/java/com/tronic/logger"

    %% Styles
    classDef core fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef listeners fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef processing fill:#98FB98,stroke:#333,stroke-width:1px
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px
    classDef persistence fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef utils fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
```
