# hoanbucon/discord-bot architecture

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

- Interactive diagram: https://gitdiagram.com/hoanbucon/discord-bot
- Repository: https://github.com/hoanbucon/discord-bot

## Overview

##### Main Components
- Bot Entry Point: At the center is the main bot file (src/index.ts), which initializes the Discord client and sets the stage for event handling.
- Command Handlers: Under the “handlers” directory, you have CommandHandler.ts, PrefixHandler.ts, and SlashHandler.ts. These components are responsible for interpreting incoming messages and dispatching them to the corresponding commands.
- Commands: The “src/commands” directory is divided into generic command definitions (Command.ts) and a subdirectory (botCommands) containing specific command files (e.g., BanCommand.ts, KickCommand.ts, etc.) that implement the bot’s functionalities.
- Data and Media Resources: Within botCommands, the “dataFiles” subdirectory stores JSON files (like bannedUsers.json, mutedUsers.json, tictactoeData.json) and various multimedia resources used by commands (organized within media folders for meme commands).
- Utilities: The “utils” folder contains helper modules (like BanDataManager, MuteDataManager, DonutUtils, TictactoeGameplay, etc.) that encapsulate business logic, manage data persistence, and assist with various operations.
- Interfaces: The “interfaces” directory holds TypeScript interfaces which ensure consistent data structures (e.g., ICommand, IBaseData).

##### Relationships and Interactions
- The Discord Bot’s entry point (index.ts) initializes the Discord client and registers the appropriate event listeners.
- Incoming Discord events (messages, slash commands) are routed to the Command Handlers (PrefixHandler and SlashHandler) which rely on the CommandHandler to delegate the specific commands.
- Each command (e.g., BanCommand, HelpCommand) encapsulated within its file is invoked by the handler. Commands may reference their corresponding utility functions (like data managers or file utilities) to perform operations.
- The utility modules interact with the file system to read/write JSON files or load media assets, while also handling permissions and other command-specific logic.
- External dependencies (Discord.js and Bun) should be highlighted, as they support real-time communication and rapid development.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Command implementations, event handling, and business logic (in utilities) are separated into distinct directories.
- Modular Design: Commands are separated into individual files, making them easily extensible and maintainable.
- Clear Data Management: Data persistence for banned/muted users and specific game states (Tictactoe) is managed via JSON files in the dataFiles folder.

##### Final Advice
- Modular design: each command and utility is an independent unit, promoting separation of concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        ext1["Discord.js"]:::external
        ext2["Bun"]:::external
    end

    %% Bot Entry Point
    bot["Discord Bot (src/index.ts)"]:::bot

    %% Connections from External Dependencies to Bot Entry Point
    ext1 --> bot
    ext2 --> bot

    %% Handlers Cluster
    subgraph "Handlers"
        ph["PrefixHandler"]:::handler
        sh["SlashHandler"]:::handler
        ch["CommandHandler"]:::handler
    end

    %% Connections between Bot Entry Point and Handlers
    bot --> ph
    bot --> sh
    ph --> ch
    sh --> ch

    %% Commands Cluster
    subgraph "Commands"
        gen["Generic Command (Command.ts)"]:::command
        spec["Specific Commands (botCommands)"]:::command
    end

    %% Connections between Handlers and Commands
    ch --> gen
    ch --> spec

    %% Utilities Cluster
    subgraph "Utilities"
        utils["Utility Modules (src/utils)"]:::util
    end

    %% Connection from Commands to Utilities
    spec --> utils

    %% Data and Media Repositories
    subgraph "Data & Media Repositories"
        json["JSON Data Files (commandData)"]:::data
        media["Media Assets"]:::data
    end

    %% Connections from Utilities to Data & Media 
    utils --> json
    utils --> media

    %% Interfaces Cluster
    subgraph "Interfaces"
        iface["TypeScript Interfaces"]:::interface
    end

    %% Connection from Commands to Interfaces
    gen --> iface

    %% Click Events
    click bot "https://github.com/hoanbucon/discord-bot/blob/master/src/index.ts"
    click ph "https://github.com/hoanbucon/discord-bot/blob/master/src/handlers/PrefixHandler.ts"
    click sh "https://github.com/hoanbucon/discord-bot/blob/master/src/handlers/SlashHandler.ts"
    click ch "https://github.com/hoanbucon/discord-bot/blob/master/src/handlers/CommandHandler.ts"
    click gen "https://github.com/hoanbucon/discord-bot/blob/master/src/commands/Command.ts"
    click spec "https://github.com/hoanbucon/discord-bot/tree/master/src/commands/botCommands"
    click json "https://github.com/hoanbucon/discord-bot/tree/master/src/commands/botCommands/dataFiles/commandData"
    click media "https://github.com/hoanbucon/discord-bot/tree/master/src/commands/botCommands/dataFiles/media"
    click utils "https://github.com/hoanbucon/discord-bot/tree/master/src/utils"
    click iface "https://github.com/hoanbucon/discord-bot/tree/master/src/interfaces"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef bot fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef handler fill:#cceeff,stroke:#333,stroke-width:2px;
    classDef command fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef util fill:#ffe6cc,stroke:#333,stroke-width:2px;
    classDef data fill:#e6e6fa,stroke:#333,stroke-width:2px;
    classDef interface fill:#d5f5e3,stroke:#333,stroke-width:2px;
```
