# adamseidman/dsf-discord-bot architecture

> Architecture diagram of the GitHub repository adamseidman/dsf-discord-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/dsf-discord-bot
- Repository: https://github.com/adamseidman/dsf-discord-bot

## Overview

DSF-Discord-Bot is a Discord bot for generating daily “stupid facts,” with a web portal for managing bot data and settings. Its principal workflow starts with Discord events: commands and message handlers produce responses, while the fact scheduler supports daily channel posts and fact construction draws on domain data. The portal provides authenticated management and a fact-template generator. The graph also includes persistence and documented integration points; several routes and command implementations are unsampled, so uncertain call links are omitted.

Main entry points: [`web/server.js`](https://github.com/adamseidman/dsf-discord-bot/blob/master/web/server.js) (Web server), [`discord/index.js`](https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/index.js) (Discord client), [`db/database.js`](https://github.com/adamseidman/dsf-discord-bot/blob/master/db/database.js) (Database layer), [`db/tables`](https://github.com/adamseidman/dsf-discord-bot/tree/master/db/tables) (Domain tables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discord["Discord bot"]
  node_discord_runtime["Discord client<br/>[index.js]"]
  node_command_dispatch["Command dispatch<br/>[commands.js]"]
  node_commands["Bot commands"]
  node_message_handlers["Message handlers<br/>[messages.js]"]
  node_dm_handlers["Direct messages<br/>[directMessages.js]"]
  node_voice["Voice features<br/>[voice.js]"]
end

subgraph group_facts["Fact domain"]
  node_fact_builder["Fact construction<br/>[construction.js]"]
  node_fact_scheduler["Daily scheduler<br/>[scheduler.js]"]
  node_fact_override["Fact overrides<br/>[override.js]"]
end

subgraph group_web["Web portal"]
  node_web_server["Web server<br/>[server.js]"]
  node_web_get["Portal reads"]
  node_web_writes["Portal writes"]
  node_web_updates["Portal updates"]
  node_portal_ui["Portal interface<br/>[portal.js]"]
  node_template_generator["Template generator<br/>[generator.js]"]
end

subgraph group_data["Persistence"]
  node_database["Database layer<br/>[database.js]"]
  node_domain_tables[("Domain tables")]
  node_media_buckets[("Media buckets")]
end

subgraph group_integrations["Integrations"]
  node_supabase[("Supabase")]
  node_external_apis["External APIs"]
  node_date_nager["Holiday service<br/>[dateNager.js]"]
  node_discord_service["Discord"]
end

node_discord_user(("Discord user"))
node_web_user(("Portal user"))

node_discord_user -->|"sends events"| node_discord_runtime
node_discord_runtime -->|"dispatches commands"| node_command_dispatch
node_discord_runtime -->|"dispatches messages"| node_message_handlers
node_discord_runtime -->|"dispatches DMs"| node_dm_handlers
node_command_dispatch -->|"dispatches command"| node_commands
node_discord_runtime -->|"schedules channels"| node_fact_scheduler
node_fact_builder -->|"reads domain data"| node_domain_tables
node_discord_runtime -->|"connects"| node_discord_service
node_web_user -->|"requests portal"| node_web_server
node_web_server -->|"dispatches GET"| node_web_get
node_web_server -->|"dispatches POST"| node_web_writes
node_web_server -->|"dispatches PUT"| node_web_updates
node_portal_ui -->|"calls portal API"| node_web_server
node_web_server -->|"authenticates users"| node_domain_tables
node_web_server -->|"stores sessions"| node_database
node_database -->|"initializes tables"| node_domain_tables
node_database -->|"initializes buckets"| node_media_buckets
node_database -->|"reads and writes"| node_supabase
node_date_nager -->|"fetches holidays"| node_external_apis

click node_discord_runtime "https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/index.js"
click node_command_dispatch "https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/modules/commands.js"
click node_commands "https://github.com/adamseidman/dsf-discord-bot/tree/master/discord/commands"
click node_message_handlers "https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/modules/messages.js"
click node_dm_handlers "https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/modules/directMessages.js"
click node_voice "https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/modules/voice.js"
click node_fact_builder "https://github.com/adamseidman/dsf-discord-bot/blob/master/fact/construction.js"
click node_fact_scheduler "https://github.com/adamseidman/dsf-discord-bot/blob/master/fact/scheduler.js"
click node_fact_override "https://github.com/adamseidman/dsf-discord-bot/blob/master/fact/override.js"
click node_web_server "https://github.com/adamseidman/dsf-discord-bot/blob/master/web/server.js"
click node_web_get "https://github.com/adamseidman/dsf-discord-bot/tree/master/web/get"
click node_web_writes "https://github.com/adamseidman/dsf-discord-bot/tree/master/web/post"
click node_web_updates "https://github.com/adamseidman/dsf-discord-bot/tree/master/web/put"
click node_portal_ui "https://github.com/adamseidman/dsf-discord-bot/blob/master/web/public/js/portal.js"
click node_template_generator "https://github.com/adamseidman/dsf-discord-bot/blob/master/web/public/generator/generator.js"
click node_database "https://github.com/adamseidman/dsf-discord-bot/blob/master/db/database.js"
click node_domain_tables "https://github.com/adamseidman/dsf-discord-bot/tree/master/db/tables"
click node_media_buckets "https://github.com/adamseidman/dsf-discord-bot/tree/master/db/media"
click node_external_apis "https://github.com/adamseidman/dsf-discord-bot/tree/master/apis"
click node_date_nager "https://github.com/adamseidman/dsf-discord-bot/blob/master/apis/dateNager.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_runtime,node_command_dispatch,node_commands,node_message_handlers,node_dm_handlers,node_voice,node_discord_user,node_web_user toneBlue
class node_fact_builder,node_fact_scheduler,node_fact_override toneAmber
class node_web_server,node_web_get,node_web_writes,node_web_updates,node_portal_ui,node_template_generator toneMint
class node_database,node_domain_tables,node_media_buckets toneRose
class node_supabase,node_external_apis,node_date_nager,node_discord_service toneIndigo
```

## Components

### Discord bot

- [Discord client](https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/index.js): `discord/index.js`
- [Command dispatch](https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/modules/commands.js): `discord/modules/commands.js`
- [Bot commands](https://github.com/adamseidman/dsf-discord-bot/tree/master/discord/commands): `discord/commands`
- [Message handlers](https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/modules/messages.js): `discord/modules/messages.js`
- [Direct messages](https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/modules/directMessages.js): `discord/modules/directMessages.js`
- [Voice features](https://github.com/adamseidman/dsf-discord-bot/blob/master/discord/modules/voice.js): `discord/modules/voice.js`

### Fact domain

- [Fact construction](https://github.com/adamseidman/dsf-discord-bot/blob/master/fact/construction.js): `fact/construction.js`
- [Daily scheduler](https://github.com/adamseidman/dsf-discord-bot/blob/master/fact/scheduler.js): `fact/scheduler.js`
- [Fact overrides](https://github.com/adamseidman/dsf-discord-bot/blob/master/fact/override.js): `fact/override.js`

### Web portal

- [Web server](https://github.com/adamseidman/dsf-discord-bot/blob/master/web/server.js): `web/server.js`
- [Portal reads](https://github.com/adamseidman/dsf-discord-bot/tree/master/web/get): `web/get`
- [Portal writes](https://github.com/adamseidman/dsf-discord-bot/tree/master/web/post): `web/post`
- [Portal updates](https://github.com/adamseidman/dsf-discord-bot/tree/master/web/put): `web/put`
- [Portal interface](https://github.com/adamseidman/dsf-discord-bot/blob/master/web/public/js/portal.js): `web/public/js/portal.js`
- [Template generator](https://github.com/adamseidman/dsf-discord-bot/blob/master/web/public/generator/generator.js): `web/public/generator/generator.js`

### Persistence

- [Database layer](https://github.com/adamseidman/dsf-discord-bot/blob/master/db/database.js): `db/database.js`
- [Domain tables](https://github.com/adamseidman/dsf-discord-bot/tree/master/db/tables): `db/tables`
- [Media buckets](https://github.com/adamseidman/dsf-discord-bot/tree/master/db/media): `db/media`

### Integrations

- **Supabase**
- [External APIs](https://github.com/adamseidman/dsf-discord-bot/tree/master/apis): `apis`
- [Holiday service](https://github.com/adamseidman/dsf-discord-bot/blob/master/apis/dateNager.js): `apis/dateNager.js`
- **Discord**

### Other components

- **Discord user**
- **Portal user**

## Connections

- Discord user → Discord client: sends events
- Discord client → Command dispatch: dispatches commands
- Discord client → Message handlers: dispatches messages
- Discord client → Direct messages: dispatches DMs
- Command dispatch → Bot commands: dispatches command
- Discord client → Daily scheduler: schedules channels
- Fact construction → Domain tables: reads domain data
- Discord client → Discord: connects
- Portal user → Web server: requests portal
- Web server → Portal reads: dispatches GET
- Web server → Portal writes: dispatches POST
- Web server → Portal updates: dispatches PUT
- Portal interface → Web server: calls portal API
- Web server → Domain tables: authenticates users
- Web server → Database layer: stores sessions
- Database layer → Domain tables: initializes tables
- Database layer → Media buckets: initializes buckets
- Database layer → Supabase: reads and writes
- Holiday service → External APIs: fetches holidays