# adamseidman/spotify-guesser-bot architecture

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

- Interactive diagram: https://gitdiagram.com/adamseidman/spotify-guesser-bot
- Repository: https://github.com/adamseidman/spotify-guesser-bot

## Overview

Songs Chain Discord Bot lets server members build song-title chains by posting prefixed guesses; the bot checks each guess against the current game, validates it against Spotify, and updates the chain or ends the round. Discord interactions also expose server setup, challenges, shuffle, history, leaderboards, statistics, and help. Game state and persistent histories, rules, and results are handled through the database layer. The graph follows the sampled entry point, game, command, Spotify, and database code; some command implementations are represented by their paths without asserting unsampled internal wiring.

Main entry points: [`base/commands.js`](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/commands.js) (Command router), [`base/db.js`](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/db.js) (Persistent game data), [`base/slash-commands/set.js`](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/set.js) (Server settings), [`base/game.js`](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/game.js) (Game state and rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discord_runtime["Discord runtime"]
  node_client["Bot client<br/>[client.js]"]
  node_commands["Command router<br/>[commands.js]"]
  node_request_queue["Request queue<br/>[reqHandling.js]"]
end

subgraph group_gameplay["Chain gameplay"]
  node_game["Game state and rules<br/>[game.js]"]
  node_spotify["Track search<br/>[spotify.js]"]
end

subgraph group_server_features["Server features"]
  node_settings["Server settings<br/>[set.js]"]
  node_challenges["Song challenges<br/>[challenge.js]"]
  node_shuffle["Chain shuffle<br/>[shuffle.js]"]
  node_history["Chain history<br/>[history.js]"]
  node_leaderboard["Leaderboards<br/>[leaderboard.js]"]
  node_stats["Game statistics<br/>[stats.js]"]
  node_help["Help and guidance<br/>[help.js]"]
end

subgraph group_data_services["Data services"]
  node_database[("Persistent game data<br/>[db.js]")]
end

node_member(("Server member"))
node_discord["Discord platform"]
node_spotify_api["Spotify API"]

node_member -->|"sends events"| node_discord
node_discord -->|"delivers events"| node_client
node_client -->|"routes interactions"| node_commands
node_client -->|"enqueues messages"| node_request_queue
node_request_queue -->|"dispatches messages"| node_commands
node_commands -->|"reads server rules"| node_database
node_commands -->|"submits guesses"| node_game
node_game -->|"requests tracks"| node_spotify
node_spotify -->|"searches tracks"| node_spotify_api
node_game -->|"loads and saves state"| node_database
node_commands -->|"dispatches settings"| node_settings
node_commands -->|"dispatches challenges"| node_challenges
node_commands -->|"dispatches shuffle"| node_shuffle
node_commands -->|"dispatches history"| node_history
node_commands -->|"dispatches leaderboard"| node_leaderboard
node_commands -->|"dispatches statistics"| node_stats
node_commands -->|"dispatches help"| node_help
node_settings -->|"changes channel"| node_game
node_settings -->|"updates rules"| node_database
node_history -->|"reads histories"| node_database
node_leaderboard -->|"reads scores"| node_database
node_stats -->|"reads results"| node_database
node_commands -->|"sends game responses"| node_discord
node_settings -->|"replies to interactions"| node_discord
node_history -->|"displays history"| node_discord
node_leaderboard -->|"displays rankings"| node_discord
node_stats -->|"displays statistics"| node_discord
node_help -->|"displays guidance"| node_discord

click node_client "https://github.com/adamseidman/spotify-guesser-bot/blob/main/client/client.js"
click node_commands "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/commands.js"
click node_request_queue "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/reqHandling.js"
click node_game "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/game.js"
click node_spotify "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/spotify.js"
click node_settings "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/set.js"
click node_challenges "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/challenge.js"
click node_shuffle "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/shuffle.js"
click node_history "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/history.js"
click node_leaderboard "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/leaderboard.js"
click node_stats "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/stats.js"
click node_help "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/help.js"
click node_database "https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/db.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_client,node_commands,node_request_queue toneBlue
class node_game,node_spotify toneAmber
class node_settings,node_challenges,node_shuffle,node_history,node_leaderboard,node_stats,node_help,node_member,node_spotify_api toneMint
class node_database toneRose
class node_discord toneIndigo
```

## Components

### Discord runtime

- [Bot client](https://github.com/adamseidman/spotify-guesser-bot/blob/main/client/client.js): `client/client.js`
- [Command router](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/commands.js): `base/commands.js`
- [Request queue](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/reqHandling.js): `base/reqHandling.js`

### Chain gameplay

- [Game state and rules](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/game.js): `base/game.js`
- [Track search](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/spotify.js): `base/spotify.js`

### Server features

- [Server settings](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/set.js): `base/slash-commands/set.js`
- [Song challenges](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/challenge.js): `base/slash-commands/challenge.js`
- [Chain shuffle](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/shuffle.js): `base/slash-commands/shuffle.js`
- [Chain history](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/history.js): `base/slash-commands/history.js`
- [Leaderboards](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/leaderboard.js): `base/slash-commands/leaderboard.js`
- [Game statistics](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/stats.js): `base/slash-commands/stats.js`
- [Help and guidance](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/slash-commands/help.js): `base/slash-commands/help.js`

### Data services

- [Persistent game data](https://github.com/adamseidman/spotify-guesser-bot/blob/main/base/db.js): `base/db.js`

### Other components

- **Server member**
- **Discord platform**
- **Spotify API**

## Connections

- Server member → Discord platform: sends events
- Discord platform → Bot client: delivers events
- Bot client → Command router: routes interactions
- Bot client → Request queue: enqueues messages
- Request queue → Command router: dispatches messages
- Command router → Persistent game data: reads server rules
- Command router → Game state and rules: submits guesses
- Game state and rules → Track search: requests tracks
- Track search → Spotify API: searches tracks
- Game state and rules → Persistent game data: loads and saves state
- Command router → Server settings: dispatches settings
- Command router → Song challenges: dispatches challenges
- Command router → Chain shuffle: dispatches shuffle
- Command router → Chain history: dispatches history
- Command router → Leaderboards: dispatches leaderboard
- Command router → Game statistics: dispatches statistics
- Command router → Help and guidance: dispatches help
- Server settings → Game state and rules: changes channel
- Server settings → Persistent game data: updates rules
- Chain history → Persistent game data: reads histories
- Leaderboards → Persistent game data: reads scores
- Game statistics → Persistent game data: reads results
- Command router → Discord platform: sends game responses
- Server settings → Discord platform: replies to interactions
- Chain history → Discord platform: displays history
- Leaderboards → Discord platform: displays rankings
- Game statistics → Discord platform: displays statistics
- Help and guidance → Discord platform: displays guidance