# benj4368/merlin architecture

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

- Interactive diagram: https://gitdiagram.com/benj4368/merlin
- Repository: https://github.com/benj4368/merlin

## Overview

Merlin is a Discord bot whose main workflow is: Discord delivers an interaction, the event handler selects a command, and that command responds with a bot feature. Major branches include party games, role-play sessions, Smite challenges, media lookup, and bot administration. The graph also shows message-triggered modes and role-play state. Some command implementations and integrations are documented or indexed but were not excerpted, so those relationships are limited to what the README or shown source supports.

Main entry points: [`commands`](https://github.com/benj4368/merlin/tree/main/commands) (Slash commands), [`main.js`](https://github.com/benj4368/merlin/blob/main/main.js) (Bot startup), [`commands/rp.js`](https://github.com/benj4368/merlin/blob/main/commands/rp.js) (Role-play command), [`events/interactionCreate.js`](https://github.com/benj4368/merlin/blob/main/events/interactionCreate.js) (Interaction router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_main["Bot startup<br/>[main.js]"]
  node_interactions["Interaction router"]
  node_messages["Message handler<br/>[messageCreate.js]"]
  node_ready["Ready handler<br/>[clientReady.js]"]
end

subgraph group_games["Games and challenges"]
  node_challenge["Smite challenge<br/>[challenge.js]"]
  node_smite_resources["Smite resources"]
  node_lgow["LGOW game command<br/>[lgow.js]"]
  node_lgow_classes["Game roles and state<br/>[lgowClasses.js]"]
  node_randomgod["Random god command<br/>[randomgod.js]"]
end

subgraph group_roleplay["Role-play sessions"]
  node_rp["Role-play command<br/>[rp.js]"]
  node_rp_state["Session state<br/>[rp_data.js]"]
  node_rp_sounds["Session sound assets"]
end

subgraph group_services["Commands and modes"]
  node_commands["Slash commands"]
  node_crit["Media lookup<br/>[crit.js]"]
  node_mode["Mode command<br/>[mode.js]"]
  node_mode_state["Mode flags<br/>[varModes.js]"]
  node_reload["Reload command<br/>[reload.js]"]
  node_restart["Restart command<br/>[restart.js]"]
  node_merlin["Merlin response<br/>[merlin.js]"]
end

node_discord_users(("Discord users"))
node_discord["Discord platform"]
node_tvdb["TheTVDB API"]
node_voice["Discord voice"]

node_discord_users -->|"send interactions"| node_discord
node_discord -->|"connects bot"| node_main
node_main -->|"loads commands"| node_commands
node_main -->|"registers handler"| node_interactions
node_main -->|"registers handler"| node_messages
node_main -->|"registers handler"| node_ready
node_discord -.->|"delivers interactions"| node_interactions
node_interactions -->|"dispatches command"| node_commands
node_commands -.->|"includes feature"| node_challenge
node_challenge -.->|"reads game assets"| node_smite_resources
node_commands -->|"includes feature"| node_crit
node_crit -->|"looks up media"| node_tvdb
node_commands -->|"includes feature"| node_lgow
node_lgow -->|"creates game state"| node_lgow_classes
node_commands -->|"includes feature"| node_rp
node_rp -->|"reads session state"| node_rp_state
node_rp -->|"plays sound assets"| node_rp_sounds
node_rp -->|"joins voice channel"| node_voice
node_commands -.->|"includes command"| node_mode
node_mode -->|"updates mode flags"| node_mode_state
node_messages -->|"reads mode flags"| node_mode_state
node_commands -->|"includes command"| node_reload
node_commands -->|"includes command"| node_restart
node_commands -->|"includes command"| node_merlin
node_commands -.->|"includes command"| node_randomgod

click node_main "https://github.com/benj4368/merlin/blob/main/main.js"
click node_interactions "https://github.com/benj4368/merlin/blob/main/events/interactionCreate.js"
click node_messages "https://github.com/benj4368/merlin/blob/main/events/messageCreate.js"
click node_ready "https://github.com/benj4368/merlin/blob/main/events/clientReady.js"
click node_commands "https://github.com/benj4368/merlin/tree/main/commands"
click node_challenge "https://github.com/benj4368/merlin/blob/main/commands/challenge.js"
click node_smite_resources "https://github.com/benj4368/merlin/tree/main/resources/smite"
click node_crit "https://github.com/benj4368/merlin/blob/main/commands/crit.js"
click node_lgow "https://github.com/benj4368/merlin/blob/main/commands/lgow.js"
click node_lgow_classes "https://github.com/benj4368/merlin/blob/main/resources/lgow/lgowClasses.js"
click node_rp "https://github.com/benj4368/merlin/blob/main/commands/rp.js"
click node_rp_state "https://github.com/benj4368/merlin/blob/main/resources/rp/rp_data.js"
click node_rp_sounds "https://github.com/benj4368/merlin/tree/main/resources/rp/sounds"
click node_mode "https://github.com/benj4368/merlin/blob/main/commands/mode.js"
click node_mode_state "https://github.com/benj4368/merlin/blob/main/varModes.js"
click node_reload "https://github.com/benj4368/merlin/blob/main/commands/reload.js"
click node_restart "https://github.com/benj4368/merlin/blob/main/commands/restart.js"
click node_merlin "https://github.com/benj4368/merlin/blob/main/commands/merlin.js"
click node_randomgod "https://github.com/benj4368/merlin/blob/main/commands/randomgod.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_main,node_interactions,node_messages,node_ready,node_discord_users toneBlue
class node_challenge,node_smite_resources,node_lgow,node_lgow_classes,node_randomgod toneAmber
class node_rp,node_rp_state,node_rp_sounds,node_tvdb toneMint
class node_commands,node_crit,node_mode,node_mode_state,node_reload,node_restart,node_merlin toneRose
class node_discord,node_voice toneIndigo
```

## Components

### Bot runtime

- [Bot startup](https://github.com/benj4368/merlin/blob/main/main.js): `main.js`
- [Interaction router](https://github.com/benj4368/merlin/blob/main/events/interactionCreate.js): `events/interactionCreate.js`
- [Message handler](https://github.com/benj4368/merlin/blob/main/events/messageCreate.js): `events/messageCreate.js`
- [Ready handler](https://github.com/benj4368/merlin/blob/main/events/clientReady.js): `events/clientReady.js`

### Games and challenges

- [Smite challenge](https://github.com/benj4368/merlin/blob/main/commands/challenge.js): `commands/challenge.js`
- [Smite resources](https://github.com/benj4368/merlin/tree/main/resources/smite): `resources/smite`
- [LGOW game command](https://github.com/benj4368/merlin/blob/main/commands/lgow.js): `commands/lgow.js`
- [Game roles and state](https://github.com/benj4368/merlin/blob/main/resources/lgow/lgowClasses.js): `resources/lgow/lgowClasses.js`
- [Random god command](https://github.com/benj4368/merlin/blob/main/commands/randomgod.js): `commands/randomgod.js`

### Role-play sessions

- [Role-play command](https://github.com/benj4368/merlin/blob/main/commands/rp.js): `commands/rp.js`
- [Session state](https://github.com/benj4368/merlin/blob/main/resources/rp/rp_data.js): `resources/rp/rp_data.js`
- [Session sound assets](https://github.com/benj4368/merlin/tree/main/resources/rp/sounds): `resources/rp/sounds`

### Commands and modes

- [Slash commands](https://github.com/benj4368/merlin/tree/main/commands): `commands`
- [Media lookup](https://github.com/benj4368/merlin/blob/main/commands/crit.js): `commands/crit.js`
- [Mode command](https://github.com/benj4368/merlin/blob/main/commands/mode.js): `commands/mode.js`
- [Mode flags](https://github.com/benj4368/merlin/blob/main/varModes.js): `varModes.js`
- [Reload command](https://github.com/benj4368/merlin/blob/main/commands/reload.js): `commands/reload.js`
- [Restart command](https://github.com/benj4368/merlin/blob/main/commands/restart.js): `commands/restart.js`
- [Merlin response](https://github.com/benj4368/merlin/blob/main/commands/merlin.js): `commands/merlin.js`

### Other components

- **Discord users**
- **Discord platform**
- **TheTVDB API**
- **Discord voice**

## Connections

- Discord users → Discord platform: send interactions (evidence: `readme.md`)
- Discord platform → Bot startup: connects bot (evidence: `main.js`)
- Bot startup → Slash commands: loads commands (evidence: `main.js`)
- Bot startup → Interaction router: registers handler (evidence: `main.js`)
- Bot startup → Message handler: registers handler (evidence: `main.js`)
- Bot startup → Ready handler: registers handler (evidence: `main.js`)
- Discord platform → Interaction router: delivers interactions
- Interaction router → Slash commands: dispatches command (evidence: `events/interactionCreate.js`)
- Slash commands → Smite challenge: includes feature
- Smite challenge → Smite resources: reads game assets
- Slash commands → Media lookup: includes feature (evidence: `readme.md`)
- Media lookup → TheTVDB API: looks up media (evidence: `readme.md`)
- Slash commands → LGOW game command: includes feature (evidence: `readme.md`)
- LGOW game command → Game roles and state: creates game state (evidence: `commands/lgow.js`)
- Slash commands → Role-play command: includes feature (evidence: `readme.md`)
- Role-play command → Session state: reads session state (evidence: `commands/rp.js`)
- Role-play command → Session sound assets: plays sound assets (evidence: `commands/rp.js`)
- Role-play command → Discord voice: joins voice channel (evidence: `commands/rp.js`)
- Slash commands → Mode command: includes command
- Mode command → Mode flags: updates mode flags (evidence: `commands/mode.js`)
- Message handler → Mode flags: reads mode flags (evidence: `events/messageCreate.js`)
- Slash commands → Reload command: includes command (evidence: `readme.md`)
- Slash commands → Restart command: includes command (evidence: `readme.md`)
- Slash commands → Merlin response: includes command (evidence: `readme.md`)
- Slash commands → Random god command: includes command