# doiska/twokei-next architecture

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

- Interactive diagram: https://gitdiagram.com/doiska/twokei-next
- Repository: https://github.com/doiska/twokei-next

## Overview

##### Project Type and Purpose
- This is a Discord music bot built using Node.js and TypeScript.
- The README indicates that it manages music playback via integration with Spotify, YouTube (via resolver modules), and handles Discord interactions (commands, buttons, embeds).
- It covers several domains: command handling, music playback management, database integration (via Postgres and Drizzle migrations), localization, and scheduled jobs.

##### File Structure
- Top-Level Directories:
- .docker: Contains Dockerfiles and docker-compose settings for containerized deployment.
- drizzle: Houses database migration scripts and snapshots.
- src: Contains the main application code.
- Inside src, notice key subdirectories:
- app: Core application initialization files and environment configuration.
- commands: Contains various bot commands (like a setup command).
- db: Contains database connection logic and schemas for different modules (users, guilds, ranking, etc.).
- i18n: Handles internationalization and localization (with separate locales for English and Portuguese).
- interaction-handlers: Focus on user-driven events such as button clicks (donate, profile) and music control interactions.
- listeners: Register event listeners related to debug, guild setup, music events, ranking events, and voice channel events.
- music: This is a key focal point further divided into:
o controllers: E.g., “Xiao” (player manager) and “Venti” (handles player responses from lavaplayer).
o functions: Specific music operations like adding a song, skipping, pausing, etc.
o interfaces, resolvers (Spotify, YouTube), sessions (managing player sessions), song-channel configuration, and utility functions.
- lib: Contains helper modules such as analytics, cron jobs (with scheduled tasks like refreshing ranking or checking node statuses), logger, lru-cache, and message handling.
- structures: Holds custom classes including the main Discord Bot client (TwokeiClient) and scope-specific exceptions.

a. Main Components to Include:
- Discord Bot Client – Represented by TwokeiClient along with shard management (src/shard.ts). This is the entry point handling connection to Discord.
- Command and Interaction Handling – Modules in src/commands and src/interaction-handlers that parse and route user inputs.
- Music Subsystem:
- Music Controllers (Xiao & Venti) for managing playback and handling responses.
- Music Functions providing operations like add-new-song, skip, pause, etc.
- Music Sessions and SongChannel setup to manage state and communication with channels.
- Resolvers for external music sources, e.g., Spotify and YouTube.
- Localization (i18n) – Show separate module for handling multiple locales (en_us, pt_br) that feeds into message rendering.
- Scheduled Jobs (Cron) – The cron library in src/lib/cron and its jobs (check nodes statuses, refresh ranking, refresh rich presence) to perform periodic background tasks.
- Utilities and Supporting Libraries – Include logging, message handler, and LRU cache which support the higher-level functionalities.
- Docker/Deployment – Although not a runtime component, include a node indicating container configuration via the .docker files.

b. Relationships and Interactions:
- From these handlers, illustrate calls to the Music Subsystem components (controllers, functions, sessions) and also interactions with the database.
- That the Music Subsystem uses external API resolvers to fetch music (e.g., from YouTube or Spotify) via dedicated resolver modules.
- The Database (Postgres) should be connected with modules in src/db, both writing analytics (via src/lib/analytics) and reading/updating user and guild data.
- The Cron subsystem periodically triggers tasks which may update the database or the state of the Music and Message systems.
- Localization services provide language-specific messages to be rendered by command and interaction handlers.

c. Architectural Patterns and Technologies:
- Modular design and separation of concerns (e.g., splitting command logic, music control, and database operations).
- Notice the use of event-driven programming in Discord listeners and interaction handlers.
- Key technologies/libraries: TypeScript, Node.js, Postgres (with Drizzle for migrations), Docker for containerization, and possibly external libraries (lavaplayer integration hinted by Venti).
- Utilization of cron jobs suggests background processing and scheduled task patterns.

- For the full-stack nature adapted to a Discord bot:
- Separate clearly the Discord interface (client and event handlers) from the backend logic (music subsystem, database modules, cron jobs).
- How commands and interactions flow into the bot’s business logic (music control, message generation) and further interact with persistence (Postgres).

- Clearly labeled components and modules such as:
- Discord Bot Client (TwokeiClient and shard)
- Command Processor/Interaction Handlers (commands, listeners)
- Music Subsystem (controllers, functions, sessions, resolvers)
- Database Integration (Postgres via drizzle and schemas)
- Scheduled Cron Jobs (with specific job names like refresh-ranking)
- Localization/I18n (locales organization and i18n logic)
- Utilities and Helpers (logger, message handler, cache)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Discord Layer
    subgraph "Discord Interface"
        TC["TwokeiClient"]:::discord
        S["Shard"]:::discord
    end

    %% Command & Interaction Layer
    subgraph "Command & Interaction Handlers"
        CMD["Commands"]:::interaction
        INT["Interaction Handlers"]:::interaction
    end

    %% Music Subsystem Layer
    subgraph "Music Subsystem"
        MC["Music Controllers"]:::music
        MF["Music Functions"]:::music
        MS["Music Sessions"]:::music
        MR["Music Resolvers"]:::music
        SC["Song Channel Setup"]:::music
    end

    %% Database Integration Layer
    subgraph "Database Integration"
        DB["DB Connection & Logic"]:::database
        SCH["Schema Definitions"]:::database
        MIG["Database Migrations"]:::database
    end

    %% Localization Layer
    LOC["Localization Service (i18n)"]:::localization

    %% Scheduled Cron Jobs Layer
    CRON["Cron Scheduler"]:::cron

    %% Utilities & Supporting Libraries
    subgraph "Utilities & Helpers"
        LOG["Logger"]:::utility
        CACHE["Cache (LRU)"]:::utility
        MH["Message Handler"]:::utility
        ANA["Analytics"]:::utility
    end

    %% Docker/Deployment
    DOCK["Docker Deployment"]:::docker

    %% Connections
    TC -->|"triggers"| CMD
    TC -->|"triggers"| INT

    CMD -->|"processes command"| MC
    INT -->|"processes interaction"| MC

    MC -->|"invokes"| MF
    MC -->|"manages"| MS
    MC -->|"queries"| MR
    MC -->|"configures"| SC

    CMD -->|"fetches messages"| LOC
    INT -->|"fetches messages"| LOC

    CMD -->|"updates"| DB
    INT -->|"updates"| DB
    MF -->|"persists"| DB
    MS -->|"persists"| DB
    SCH -->|"defines"| DB

    CRON -->|"schedules updates"| DB
    CRON -->|"triggers tasks in"| MF

    LOG --- CMD
    LOG --- MC
    CACHE --- CMD
    CACHE --- MF
    MH --- CMD
    ANA --- DB

    DOCK --- TC
    DOCK --- CMD
    DOCK --- CRON

    %% Styles
    classDef discord fill:#AEDFF7,stroke:#333,stroke-width:2px
    classDef interaction fill:#C7F0DB,stroke:#333,stroke-width:2px
    classDef music fill:#FFF9B0,stroke:#333,stroke-width:2px
    classDef database fill:#D3D3D3,stroke:#333,stroke-width:2px
    classDef localization fill:#F5A9A9,stroke:#333,stroke-width:2px
    classDef cron fill:#F5B7B1,stroke:#333,stroke-width:2px
    classDef utility fill:#DAC4FF,stroke:#333,stroke-width:2px
    classDef docker fill:#FFDAB9,stroke:#333,stroke-width:2px

    %% Click Events
    click TC "https://github.com/doiska/twokei-next/blob/main/src/structures/TwokeiClient.ts"
    click S "https://github.com/doiska/twokei-next/blob/main/src/shard.ts"
    click CMD "https://github.com/doiska/twokei-next/tree/main/src/commands"
    click INT "https://github.com/doiska/twokei-next/tree/main/src/interaction-handlers"
    click MC "https://github.com/doiska/twokei-next/tree/main/src/music/controllers"
    click MF "https://github.com/doiska/twokei-next/tree/main/src/music/functions"
    click MS "https://github.com/doiska/twokei-next/tree/main/src/music/sessions"
    click MR "https://github.com/doiska/twokei-next/tree/main/src/music/resolvers"
    click SC "https://github.com/doiska/twokei-next/tree/main/src/music/song-channel"
    click DB "https://github.com/doiska/twokei-next/tree/main/src/db"
    click SCH "https://github.com/doiska/twokei-next/tree/main/src/db/schemas"
    click MIG "https://github.com/doiska/twokei-next/tree/main/drizzle"
    click LOC "https://github.com/doiska/twokei-next/tree/main/src/i18n"
    click CRON "https://github.com/doiska/twokei-next/tree/main/src/lib/cron"
    click LOG "https://github.com/doiska/twokei-next/blob/main/src/lib/logger.ts"
    click CACHE "https://github.com/doiska/twokei-next/blob/main/src/lib/lru-cache.ts"
    click MH "https://github.com/doiska/twokei-next/tree/main/src/lib/message-handler"
    click ANA "https://github.com/doiska/twokei-next/tree/main/src/lib/analytics"
    click DOCK "https://github.com/doiska/twokei-next/blob/main/.docker"
```
