# brainicism/kmq_discord architecture

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

- Interactive diagram: https://gitdiagram.com/brainicism/kmq_discord
- Repository: https://github.com/brainicism/kmq_discord

## Overview

##### Project’s Main Components
- Discord Bot Client: This component is responsible for connecting to the Discord gateway, listening for Discord events (e.g., messageCreate, guildCreate, voice events), and sending updates. (See files in src/events/client and src/kmq.ts, src/kmq_client.ts)
- Command Handler & Game Logic: The heart of the bot lies in the commands (admin, game-based, misc) and game service modules (src/commands/*, src/kmq_service.ts, src/kmq_worker.ts). This section processes user inputs (commands like /play) and manages the game flow (starting a game, handling guesses, calculating scores, etc.).
- Database & Persistence: Multiple SQL migration scripts (in src/migrations and sql folders), seed data (src/seed), and the configuration (knexfiles, Kysely plugins) show that the bot uses a relational database. This component handles statistics (scoreboards, analytics), song data, game sessions, and user preferences.
- Helper & Integration Services: Several files in the helpers directory handle integrations with external services (e.g., discord_utils.ts, gemini_client.ts, playlist_manager.ts, reddit_client.ts, spotify-related scripts, etc.). These support functionalities such as downloading songs, interfacing with external APIs, localization (i18n), and other utility functions.
- Web Server and UI Layers: The presence of a file like src/kmq_web_server.ts and the website-related assets (docs, templates, images) indicate an additional component that might serve API endpoints, dashboards (scoreboards, leaderboards), or web pages for gameplay instructions.
- Deployment & Development Environments: With Docker, devcontainer settings, GitHub workflows, and shell scripts (start.sh, deployment-related scripts), the project supports containerized deployment, CI/CD processes, and developer tooling.

##### Component Relationships and Data Flow
- Discord Gateway (External Service) communicates with the Discord Bot Client.
- The Bot Client passes incoming user commands and events to the Command Handler and Game Logic modules.
- The Game Logic interacts with the Database for session data, score tracking, and analytics, using SQL scripts and migrations as a backbone.
- Helper services and integrations provide supplemental data or process external media (e.g., retrieving song metadata from Daisuki’s database, fetching Spotify playlist details, etc.).
- The Web Server component may expose some of this data visually (e.g., the scoreboard seen on the website).
- Deployment and containerization aspects (Docker/devcontainer) provide the operational means for running these services in consistent environments.

##### Architectural Patterns and Technologies
- Modular Design: The clear separation between commands, events, helpers, and services indicates a modular design, where each module handles specific concerns.
- Separation of Concerns: There is a distinct division between handling Discord events/commands, the core game logic, database operations (migrations and seeds), and external integrations.
- Containerization and CI/CD: The included Docker files, devcontainer configurations, and GitHub workflows emphasize the use of containerized deployment, automated testing, and continuous integration pipelines.
- Type Safety & Linting: The presence of TypeScript configuration (tsconfig.json) and ESLint/Prettier files enforces code quality and maintainability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Component
    subgraph "External Services"
        DG("Discord Gateway"):::external
    end

    %% Discord Bot Client Layer
    subgraph "Discord Bot Client"
        DBC_E("Events Client"):::botClient
        KMQ_TS("KMQ.ts"):::botClient
        KMQ_CL("KMQ_client.ts"):::botClient
    end

    %% Command Handler & Game Logic Layer
    subgraph "Command Handler & Game Logic"
        CMD("Commands"):::logic
        KMSRV("KMQ Service"):::logic
        KMWORK("KMQ Worker"):::logic
    end

    %% Database & Persistence Layer
    subgraph "Database & Persistence"
        MIG("Migrations"):::database
        SQL("SQL Scripts"):::database
        SEED("Seed Data"):::database
        DBCFG("DB Config"):::database
    end

    %% Helper & Integration Services Layer
    subgraph "Helper & Integration Services"
        HELP("Helpers"):::helper
    end

    %% Web Server & UI Layers
    subgraph "Web Server & UI Layers"
        WEB("Web Server"):::web
        DOC("Docs"):::web
        TEMPL("Templates"):::web
    end

    %% Deployment & DevOps Environment
    subgraph "Deployment & DevOps"
        DEV("Dev Container"):::deploy
        DOCKER("Docker"):::deploy
        WORKF("Workflows"):::deploy
        START("Start Script"):::deploy
    end

    %% Connections between layers
    DG -->|"DiscordEvents"| DBC_E
    DBC_E -->|"PassCommands"| CMD
    KMQ_TS -->|"InitializeBot"| CMD
    KMQ_CL -->|"ManageConnection"| CMD

    CMD -->|"TriggerLogic"| KMSRV
    CMD -->|"TriggerLogic"| KMWORK
    CMD -->|"CallHelpers"| HELP
    CMD -->|"DBConfig"| DBCFG

    KMSRV -->|"StoreGameData"| MIG
    KMWORK -->|"RecordAnalytics"| SQL

    MIG -->|"ProvideGameData"| WEB
    SQL -->|"ProvideStats"| DOC

    %% Deployment influences
    DEV -->|"Deploys"| DBC_E
    DOCKER -->|"Deploys"| CMD
    WORKF -->|"Deploys"| MIG
    START -->|"Deploys"| WEB

    %% Styles
    classDef external fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef botClient fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef logic fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef database fill:#577590,stroke:#fff,stroke-width:2px;
    classDef helper fill:#43aa8b,stroke:#333,stroke-width:2px;
    classDef web fill:#f94144,stroke:#333,stroke-width:2px;
    classDef deploy fill:#277DA1,stroke:#fff,stroke-width:2px;

    %% Click Events for Discord Bot Client
    click DBC_E "https://github.com/brainicism/kmq_discord/tree/master/src/events/client"
    click KMQ_TS "https://github.com/brainicism/kmq_discord/blob/master/src/kmq.ts"
    click KMQ_CL "https://github.com/brainicism/kmq_discord/blob/master/src/kmq_client.ts"

    %% Click Events for Command Handler & Game Logic
    click CMD "https://github.com/brainicism/kmq_discord/tree/master/src/commands"
    click KMSRV "https://github.com/brainicism/kmq_discord/blob/master/src/kmq_service.ts"
    click KMWORK "https://github.com/brainicism/kmq_discord/blob/master/src/kmq_worker.ts"

    %% Click Events for Database & Persistence
    click MIG "https://github.com/brainicism/kmq_discord/tree/master/src/migrations"
    click SQL "https://github.com/brainicism/kmq_discord/tree/master/sql"
    click SEED "https://github.com/brainicism/kmq_discord/tree/master/src/seed"
    click DBCFG "https://github.com/brainicism/kmq_discord/blob/master/src/config/knexfile_kmq.js"

    %% Click Event for Helper & Integration Services
    click HELP "https://github.com/brainicism/kmq_discord/tree/master/src/helpers"

    %% Click Events for Web Server & UI Layers
    click WEB "https://github.com/brainicism/kmq_discord/blob/master/src/kmq_web_server.ts"
    click DOC "https://github.com/brainicism/kmq_discord/tree/master/docs"
    click TEMPL "https://github.com/brainicism/kmq_discord/tree/master/templates"

    %% Click Events for Deployment & DevOps Environment
    click DEV "https://github.com/brainicism/kmq_discord/blob/master/.devcontainer"
    click DOCKER "https://github.com/brainicism/kmq_discord/tree/master/docker"
    click WORKF "https://github.com/brainicism/kmq_discord/tree/master/.github/workflows"
    click START "https://github.com/brainicism/kmq_discord/blob/master/start.sh"
```
