# brauliorg12/music-to-easy architecture

> Architecture diagram of the GitHub repository brauliorg12/music-to-easy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brauliorg12/music-to-easy
- Repository: https://github.com/brauliorg12/music-to-easy

## Overview

A. Project Type and Purpose
##### It does not host a frontend or a database; instead it integrates with the Discord API to
- Provide slash-command panels for music bots
- Detect music events (play/stop) from other bots
- Maintain per-server/channel state in memory
- Update embeds (“Ahora suena!”) and bot activity dynamically

B. File Structure and Architectural Patterns
##### Top-Level
- Dockerfiles, Makefile, CI/CD (GitHub Actions), docker-compose.yml → deployment pipeline
- package.json, tsconfig.json → Node/TypeScript configuration
##### src/
- core/
- BotClient.ts – initializes the Discord client with intents, loads modules
- EventHandler.ts – subscribes to discord.js events, delegates
- CommandLoader.ts & InteractionLoader.ts – dynamically load slash-commands and UI interactions
- commands/
- Slash-command implementations (music, disable, autodetect, etc.)
- interactions/
- Button/modal handlers (help, close, etc.)
- utils/
- jockieMusicAnnouncer.ts – detects play/pause events from other bots, manages the “Ahora suena” embed and bot activity
- jockiePanelActions.ts – send/update/delete the persistent control panel
- stateManager.ts – tracks which channels have active panels and autodetect enabled
- musicBotEventHelpers.ts, buttonHandler.ts, cleanupSuggestions.ts, modalHandler.ts, etc. – helper functions
- deploy-commands.ts, clear-commands.ts – CLI scripts to register slash commands

##### External Service
- Discord API (gateway & REST)
##### Core Bot Layer
- BotClient
- EventHandler
- CommandLoader
- InteractionLoader
##### Feature Modules
- Slash Commands (commands/)
- Interaction Handlers (interactions/)
- Music-Event Detector (utils/musicBotEventHelpers + jockieMusicAnnouncer)
- Panel Manager (jockiePanelActions + clean-up utilities)
- State Manager (utils/stateManager)
##### Infrastructure
- Configuration (.env, .env.example)
- Docker & Docker-Compose
- CI/CD workflows (GitHub Actions)

D. Relationships & Data Flows
##### At startup
[Docker / npm run dev] → BotClient reads .env → connects to Discord API
↓
BotClient → uses CommandLoader & InteractionLoader to register handlers
↓
EventHandler subscribes to discord.js events (messageCreate, interactionCreate)
##### Slash Command Flow
Discord API → interactionCreate
→ EventHandler → dispatch to CommandLoader → execute command logic (e.g., `/music`)
→ jockiePanelActions → send or delete panel embed
→ stateManager updates channel state
##### Interaction Flow (button/modal)
Discord API → interactionCreate (button click)
→ EventHandler → dispatch to InteractionLoader → buttonHandler/modalHandler
→ jockiePanelActions or cleanupSuggestions as needed
##### Music Event Detection
Discord API → messageCreate for messages from known music bots
→ EventHandler → musicBotEventHelpers filters relevant embeds
→ jockieMusicAnnouncer →
- update “Ahora suena” embed
- update BotClient.setActivity() state
- if panel displaced, calls jockiePanelActions to reposition
- cleanup old messages via cleanupSuggestions
##### State Persistence
stateManager maintains an in-memory map of server→channel configuration
(repopulates panels on bot restart via core logic)

E. Architectural Patterns & Design Principles
##### Separation of Concerns
- core/ handles orchestration
- commands/ & interactions/ implement business logic
- utils/ encapsulate helpers and feature modules

##### Open-Source Tool Style
- Core extensibility points: CommandLoader, InteractionLoader
- How new commands or interaction handlers drop into src/commands or src/interactions
##### Discord Bot Specifics
- Discord API at the edge
- Slash command registration and event subscription
3. No Frontend or DB: omit typical web-app layers, focus on API integration and in-memory state

- “Discord API”
- “BotClient”
- “EventHandler”
- “CommandLoader” / “InteractionLoader”
- “Slash Commands Module”
- “Interaction Handlers Module”
- “Music Event Detector”
- “Panel Manager”
- “State Manager”
- “Docker / CI/CD” (optional infra)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External"
        API["Discord API (gateway & REST)"]:::external
    end

    subgraph "Core Layer"
        BotClient["BotClient"]:::core
        EventHandler["EventHandler"]:::core
        CommandLoader["CommandLoader"]:::core
        InteractionLoader["InteractionLoader"]:::core
    end

    subgraph "Feature Modules"
        subgraph "Slash Commands Module"
            SlashCmd["Slash Commands Module"]:::feature
        end
        subgraph "Interaction Handlers Module"
            IntHandler["Interaction Handlers Module"]:::feature
        end
        subgraph "Music Event Detector"
            MusicHelper["musicBotEventHelpers"]:::feature
            MusicAnnouncer["jockieMusicAnnouncer"]:::feature
        end
        subgraph "Panel Manager"
            PanelActions["jockiePanelActions"]:::feature
            Cleanup["cleanupSuggestions"]:::feature
        end
        StateMgr["State Manager"]:::feature
    end

    subgraph "Infrastructure"
        Env[".env / .env.example"]:::infra
        Docker["Docker & docker-compose"]:::infra
        CICD["CI/CD Workflows"]:::infra
        CLI["CLI Scripts (deploy & clear)"]:::infra
    end

    Docker -->|"startup"| BotClient
    Env --> BotClient
    BotClient -->|"connect"| API

    BotClient -->|"load handlers"| CommandLoader
    BotClient -->|"load handlers"| InteractionLoader

    API -->|"interactionCreate"| EventHandler
    API -->|"messageCreate"| EventHandler

    EventHandler -->|"dispatch"| CommandLoader
    EventHandler -->|"dispatch"| InteractionLoader
    EventHandler -->|"filter events"| MusicHelper

    CommandLoader --> SlashCmd
    SlashCmd --> PanelActions
    PanelActions --> API
    PanelActions --> StateMgr
    StateMgr --> PanelActions

    InteractionLoader --> IntHandler
    IntHandler --> PanelActions
    IntHandler --> Cleanup
    Cleanup --> API
    IntHandler --> StateMgr

    MusicHelper --> MusicAnnouncer
    MusicAnnouncer --> API
    MusicAnnouncer --> PanelActions
    MusicAnnouncer --> Cleanup
    MusicAnnouncer -->|"setActivity"| BotClient

    CLI --> Env
    CLI -->|"register commands"| API

    classDef external fill:#ccc,stroke:#333,stroke-width:1px
    classDef core fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef feature fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef infra fill:#ffe0b2,stroke:#333,stroke-width:1px

    click BotClient "https://github.com/brauliorg12/music-to-easy/blob/main/src/core/BotClient.ts"
    click EventHandler "https://github.com/brauliorg12/music-to-easy/blob/main/src/core/EventHandler.ts"
    click CommandLoader "https://github.com/brauliorg12/music-to-easy/blob/main/src/core/CommandLoader.ts"
    click InteractionLoader "https://github.com/brauliorg12/music-to-easy/blob/main/src/core/InteractionLoader.ts"
    click SlashCmd "https://github.com/brauliorg12/music-to-easy/tree/main/src/commands/"
    click IntHandler "https://github.com/brauliorg12/music-to-easy/tree/main/src/interactions/"
    click MusicAnnouncer "https://github.com/brauliorg12/music-to-easy/blob/main/src/utils/jockieMusicAnnouncer.ts"
    click MusicHelper "https://github.com/brauliorg12/music-to-easy/blob/main/src/utils/musicBotEventHelpers.ts"
    click PanelActions "https://github.com/brauliorg12/music-to-easy/blob/main/src/utils/jockiePanelActions.ts"
    click Cleanup "https://github.com/brauliorg12/music-to-easy/blob/main/src/utils/cleanupSuggestions.ts"
    click StateMgr "https://github.com/brauliorg12/music-to-easy/blob/main/src/utils/stateManager.ts"
    click Env "https://github.com/brauliorg12/music-to-easy/blob/main/.env.example"
    click Docker "https://github.com/brauliorg12/music-to-easy/blob/main/docker-compose.yml"
    click CICD "https://github.com/brauliorg12/music-to-easy/blob/main/.github/workflows/ci-cd.yml"
    click CLI "https://github.com/brauliorg12/music-to-easy/blob/main/src/deploy-commands.ts"
```
