# itsmaat/wd-40 architecture

> Architecture diagram of the GitHub repository itsmaat/wd-40, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itsmaat/wd-40
- Repository: https://github.com/itsmaat/wd-40

## Overview

WD-40 is a Discord bot whose main workflow is users invoking text or slash commands and receiving music, utility, moderation, or entertainment results. Discord event handlers form the runtime ingress; the README documents the command capabilities, while sampled sources show database setup, guild-manager selection, and Reddit fetching. Music sources and Gemini are documented features, but their command-to-integration wiring was not sampled, so those links are marked unverified rather than inferred as calls.

Main entry points: [`commands/text`](https://github.com/itsmaat/wd-40/tree/develop/commands/text) (Text commands), [`events/client`](https://github.com/itsmaat/wd-40/tree/develop/events/client) (Command events), [`utils/guildManager/guildManager.js`](https://github.com/itsmaat/wd-40/blob/develop/utils/guildManager/guildManager.js) (Guild manager selector), [`utils/db/databaseManager.js`](https://github.com/itsmaat/wd-40/blob/develop/utils/db/databaseManager.js) (Database manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Discord ingress"]
  node_discord_events["Command events"]
end

subgraph group_commands["Command features"]
  node_text_commands["Text commands"]
  node_slash_commands["Slash commands"]
  node_context_commands["Context commands"]
  node_fun_games["Fun and games"]
  node_moderation["Moderation tools"]
  node_ai_response["Gemini response helper"]
end

subgraph group_music["Music playback"]
  node_music_commands["Music controls"]
  node_player_helpers["Player and extractors"]
  node_youtube_streaming["YouTube streaming"]
end

subgraph group_guild["Guild configuration"]
  node_guild_facade["Guild manager selector<br/>[guildManager.js]"]
  node_db_guild_settings["Persistent guild settings"]
  node_memory_guild_settings["No-DB guild settings"]
end

subgraph group_services["Data and integrations"]
  node_db_manager["Database manager<br/>[databaseManager.js]"]
  node_migrations["Database migrations"]
  node_repositories["Table repositories<br/>[tableManager.js]"]
  node_database[("MySQL or SQLite")]
  node_reddit_fetch["Reddit post fetcher<br/>[fetchReddit.js]"]
end

node_users(("Server users"))
node_reddit_api["Reddit API"]
node_gemini_api["Gemini API"]

node_users -->|"invoke commands"| node_discord_events
node_discord_events -.->|"dispatches"| node_text_commands
node_discord_events -.->|"dispatches"| node_slash_commands
node_discord_events -.->|"dispatches"| node_context_commands
node_text_commands -->|"includes"| node_fun_games
node_slash_commands -.->|"includes"| node_moderation
node_text_commands -->|"includes"| node_moderation
node_text_commands -->|"includes"| node_music_commands
node_music_commands -.->|"uses"| node_player_helpers
node_player_helpers -.->|"uses"| node_youtube_streaming
node_text_commands -.->|"offers AI features"| node_ai_response
node_ai_response -.->|"requests responses"| node_gemini_api
node_text_commands -.->|"uses guild settings"| node_guild_facade
node_guild_facade -->|"selects with database"| node_db_guild_settings
node_guild_facade -->|"selects without database"| node_memory_guild_settings
node_db_guild_settings -->|"reads and writes"| node_repositories
node_db_manager -->|"runs migrations"| node_migrations
node_repositories -->|"uses ORM"| node_db_manager
node_db_manager -.->|"connects"| node_database
node_reddit_fetch -->|"fetches posts"| node_reddit_api
node_text_commands -.->|"offers Reddit posts"| node_reddit_fetch

click node_discord_events "https://github.com/itsmaat/wd-40/tree/develop/events/client"
click node_text_commands "https://github.com/itsmaat/wd-40/tree/develop/commands/text"
click node_slash_commands "https://github.com/itsmaat/wd-40/tree/develop/commands/slash"
click node_context_commands "https://github.com/itsmaat/wd-40/tree/develop/commands/context"
click node_fun_games "https://github.com/itsmaat/wd-40/tree/develop/commands/text/fun"
click node_moderation "https://github.com/itsmaat/wd-40/tree/develop/commands/text/utils/admin"
click node_ai_response "https://github.com/itsmaat/wd-40/blob/develop/utils/helpers/fetchGeminiResponse.js"
click node_music_commands "https://github.com/itsmaat/wd-40/tree/develop/commands/text/music"
click node_player_helpers "https://github.com/itsmaat/wd-40/tree/develop/utils/helpers/player"
click node_youtube_streaming "https://github.com/itsmaat/wd-40/blob/develop/utils/helpers/youtubei/youtubeLivesHandler.js"
click node_guild_facade "https://github.com/itsmaat/wd-40/blob/develop/utils/guildManager/guildManager.js"
click node_db_guild_settings "https://github.com/itsmaat/wd-40/tree/develop/utils/guildManager/withDatabase"
click node_memory_guild_settings "https://github.com/itsmaat/wd-40/tree/develop/utils/guildManager/withoutDatabase"
click node_db_manager "https://github.com/itsmaat/wd-40/blob/develop/utils/db/databaseManager.js"
click node_migrations "https://github.com/itsmaat/wd-40/blob/develop/utils/db/databaseMigrator.js"
click node_repositories "https://github.com/itsmaat/wd-40/blob/develop/utils/db/tableManager.js"
click node_reddit_fetch "https://github.com/itsmaat/wd-40/blob/develop/utils/reddit/fetchReddit.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_discord_events,node_users toneBlue
class node_text_commands,node_slash_commands,node_context_commands,node_fun_games,node_moderation,node_ai_response toneAmber
class node_music_commands,node_player_helpers,node_youtube_streaming,node_reddit_api,node_gemini_api toneMint
class node_guild_facade,node_db_guild_settings,node_memory_guild_settings toneRose
class node_db_manager,node_migrations,node_repositories,node_database,node_reddit_fetch toneIndigo
```

## Components

### Discord ingress

- [Command events](https://github.com/itsmaat/wd-40/tree/develop/events/client): `events/client`

### Command features

- [Text commands](https://github.com/itsmaat/wd-40/tree/develop/commands/text): `commands/text`
- [Slash commands](https://github.com/itsmaat/wd-40/tree/develop/commands/slash): `commands/slash`
- [Context commands](https://github.com/itsmaat/wd-40/tree/develop/commands/context): `commands/context`
- [Fun and games](https://github.com/itsmaat/wd-40/tree/develop/commands/text/fun): `commands/text/fun`
- [Moderation tools](https://github.com/itsmaat/wd-40/tree/develop/commands/text/utils/admin): `commands/text/utils/admin`
- [Gemini response helper](https://github.com/itsmaat/wd-40/blob/develop/utils/helpers/fetchGeminiResponse.js): `utils/helpers/fetchGeminiResponse.js`

### Music playback

- [Music controls](https://github.com/itsmaat/wd-40/tree/develop/commands/text/music): `commands/text/music`
- [Player and extractors](https://github.com/itsmaat/wd-40/tree/develop/utils/helpers/player): `utils/helpers/player`
- [YouTube streaming](https://github.com/itsmaat/wd-40/blob/develop/utils/helpers/youtubei/youtubeLivesHandler.js): `utils/helpers/youtubei/youtubeLivesHandler.js`

### Guild configuration

- [Guild manager selector](https://github.com/itsmaat/wd-40/blob/develop/utils/guildManager/guildManager.js): `utils/guildManager/guildManager.js`
- [Persistent guild settings](https://github.com/itsmaat/wd-40/tree/develop/utils/guildManager/withDatabase): `utils/guildManager/withDatabase`
- [No-DB guild settings](https://github.com/itsmaat/wd-40/tree/develop/utils/guildManager/withoutDatabase): `utils/guildManager/withoutDatabase`

### Data and integrations

- [Database manager](https://github.com/itsmaat/wd-40/blob/develop/utils/db/databaseManager.js): `utils/db/databaseManager.js`
- [Database migrations](https://github.com/itsmaat/wd-40/blob/develop/utils/db/databaseMigrator.js): `utils/db/databaseMigrator.js`
- [Table repositories](https://github.com/itsmaat/wd-40/blob/develop/utils/db/tableManager.js): `utils/db/tableManager.js`
- **MySQL or SQLite**
- [Reddit post fetcher](https://github.com/itsmaat/wd-40/blob/develop/utils/reddit/fetchReddit.js): `utils/reddit/fetchReddit.js`

### Other components

- **Server users**
- **Reddit API**
- **Gemini API**

## Connections

- Server users → Command events: invoke commands
- Command events → Text commands: dispatches
- Command events → Slash commands: dispatches
- Command events → Context commands: dispatches
- Text commands → Fun and games: includes
- Slash commands → Moderation tools: includes
- Text commands → Moderation tools: includes
- Text commands → Music controls: includes
- Music controls → Player and extractors: uses
- Player and extractors → YouTube streaming: uses
- Text commands → Gemini response helper: offers AI features
- Gemini response helper → Gemini API: requests responses
- Text commands → Guild manager selector: uses guild settings
- Guild manager selector → Persistent guild settings: selects with database (evidence: `utils/guildManager/guildManager.js`)
- Guild manager selector → No-DB guild settings: selects without database (evidence: `utils/guildManager/guildManager.js`)
- Persistent guild settings → Table repositories: reads and writes (evidence: `utils/guildManager/withDatabase/autoReactions.js`)
- Database manager → Database migrations: runs migrations (evidence: `utils/db/databaseManager.js`)
- Table repositories → Database manager: uses ORM (evidence: `utils/db/tableManager.js`)
- Database manager → MySQL or SQLite: connects
- Reddit post fetcher → Reddit API: fetches posts (evidence: `utils/reddit/fetchReddit.js`)
- Text commands → Reddit post fetcher: offers Reddit posts