# steffleupagus/dm-secretary architecture

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

- Interactive diagram: https://gitdiagram.com/steffleupagus/dm-secretary
- Repository: https://github.com/steffleupagus/dm-secretary

## Overview

DM-Secretary is a Discord server bot for roleplay communities, combining game administration with roleplay, guild, quest, and activity features. Discord interactions enter through the bot’s registered event and command handlers; one key workflow parses Avrae quest messages, updates quest records, and reacts with summaries. Other branches support guild roles, table management, scene and travel operations, and channel activity tracking. The excerpts establish several dispatch and persistence links, but not the full command wiring or most feature internals, so uncertain relationships are omitted.

Main entry points: [`handlers/commands`](https://github.com/steffleupagus/dm-secretary/tree/main/handlers/commands) (Command handlers), [`bot.js`](https://github.com/steffleupagus/dm-secretary/blob/main/bot.js) (Bot loader), [`handlers/events`](https://github.com/steffleupagus/dm-secretary/tree/main/handlers/events) (Event handlers), [`handlers/commands/cmd_Table.js`](https://github.com/steffleupagus/dm-secretary/blob/main/handlers/commands/cmd_Table.js) (Table management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_bot["Bot loader<br/>[bot.js]"]
  node_events["Event handlers"]
  node_commands["Command handlers"]
  node_messages["Message handlers"]
  node_dashboard["Health dashboard<br/>[index.js]"]
end

subgraph group_roleplay["Roleplay operations"]
  node_scene["Scene workflow<br/>[funcsScene.js]"]
  node_travel["Travel commands<br/>[cmd_Travel.js]"]
  node_table_cmd["Table management<br/>[cmd_Table.js]"]
  node_table_ops["Table operations<br/>[funcsTable.js]"]
end

subgraph group_community["Community features"]
  node_guild["Guild roles<br/>[cmd_Guild.js]"]
end

subgraph group_tracking["Activity and records"]
  node_quest_parser["Quest parser<br/>[questMsg.js]"]
  node_activity_timer["Activity updater<br/>[activityUpdate.js]"]
end

subgraph group_state["Persistent state"]
  node_quest_store[("Quest records<br/>[questSchema.js]")]
  node_schemas[("MongoDB models")]
end

node_discord(("Discord users"))
node_discord_api["Discord API"]
node_mongo[("MongoDB")]

node_discord -->|"sends interactions"| node_discord_api
node_discord_api -->|"dispatches events"| node_events
node_bot -->|"registers"| node_events
node_bot -->|"loads commands"| node_commands
node_bot -->|"loads handlers"| node_messages
node_bot -.->|"can enable"| node_dashboard
node_events -->|"routes interactions"| node_commands
node_events -.->|"dispatches messages"| node_messages
node_commands -.->|"handles guild commands"| node_guild
node_commands -.->|"handles table commands"| node_table_cmd
node_commands -.->|"invokes scene logic"| node_scene
node_commands -.->|"handles travel"| node_travel
node_messages -.->|"dispatches quest messages"| node_quest_parser
node_quest_parser -->|"updates records"| node_quest_store
node_quest_parser -->|"adds reactions"| node_discord_api
node_table_cmd -->|"awards table"| node_table_ops
node_table_cmd -.->|"stores table data"| node_schemas
node_activity_timer -->|"reads activity metadata"| node_schemas
node_activity_timer -->|"updates channel embeds"| node_discord_api
node_dashboard -->|"checks connection"| node_mongo
node_bot -->|"connects"| node_mongo
node_quest_store -->|"persists records"| node_mongo
node_schemas -.->|"defines models"| node_mongo

click node_bot "https://github.com/steffleupagus/dm-secretary/blob/main/bot.js"
click node_events "https://github.com/steffleupagus/dm-secretary/tree/main/handlers/events"
click node_commands "https://github.com/steffleupagus/dm-secretary/tree/main/handlers/commands"
click node_messages "https://github.com/steffleupagus/dm-secretary/tree/main/handlers/message"
click node_dashboard "https://github.com/steffleupagus/dm-secretary/blob/main/dashboard/index.js"
click node_scene "https://github.com/steffleupagus/dm-secretary/blob/main/utilities/funcsScene.js"
click node_travel "https://github.com/steffleupagus/dm-secretary/blob/main/handlers/commands/cmd_Travel.js"
click node_table_cmd "https://github.com/steffleupagus/dm-secretary/blob/main/handlers/commands/cmd_Table.js"
click node_table_ops "https://github.com/steffleupagus/dm-secretary/blob/main/utilities/funcsTable.js"
click node_guild "https://github.com/steffleupagus/dm-secretary/blob/main/handlers/commands/cmd_Guild.js"
click node_quest_parser "https://github.com/steffleupagus/dm-secretary/blob/main/handlers/message/questMsg.js"
click node_activity_timer "https://github.com/steffleupagus/dm-secretary/blob/main/handlers/timers/activityUpdate.js"
click node_quest_store "https://github.com/steffleupagus/dm-secretary/blob/main/database/questSchema.js"
click node_schemas "https://github.com/steffleupagus/dm-secretary/tree/main/database"

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_bot,node_events,node_commands,node_messages,node_dashboard,node_discord toneBlue
class node_scene,node_travel,node_table_cmd,node_table_ops,node_mongo toneAmber
class node_guild,node_discord_api toneMint
class node_quest_parser,node_activity_timer toneRose
class node_quest_store,node_schemas toneIndigo
```

## Components

### Bot runtime

- [Bot loader](https://github.com/steffleupagus/dm-secretary/blob/main/bot.js): `bot.js`
- [Event handlers](https://github.com/steffleupagus/dm-secretary/tree/main/handlers/events): `handlers/events`
- [Command handlers](https://github.com/steffleupagus/dm-secretary/tree/main/handlers/commands): `handlers/commands`
- [Message handlers](https://github.com/steffleupagus/dm-secretary/tree/main/handlers/message): `handlers/message`
- [Health dashboard](https://github.com/steffleupagus/dm-secretary/blob/main/dashboard/index.js): `dashboard/index.js`

### Roleplay operations

- [Scene workflow](https://github.com/steffleupagus/dm-secretary/blob/main/utilities/funcsScene.js): `utilities/funcsScene.js`
- [Travel commands](https://github.com/steffleupagus/dm-secretary/blob/main/handlers/commands/cmd_Travel.js): `handlers/commands/cmd_Travel.js`
- [Table management](https://github.com/steffleupagus/dm-secretary/blob/main/handlers/commands/cmd_Table.js): `handlers/commands/cmd_Table.js`
- [Table operations](https://github.com/steffleupagus/dm-secretary/blob/main/utilities/funcsTable.js): `utilities/funcsTable.js`

### Community features

- [Guild roles](https://github.com/steffleupagus/dm-secretary/blob/main/handlers/commands/cmd_Guild.js): `handlers/commands/cmd_Guild.js`

### Activity and records

- [Quest parser](https://github.com/steffleupagus/dm-secretary/blob/main/handlers/message/questMsg.js): `handlers/message/questMsg.js`
- [Activity updater](https://github.com/steffleupagus/dm-secretary/blob/main/handlers/timers/activityUpdate.js): `handlers/timers/activityUpdate.js`

### Persistent state

- [Quest records](https://github.com/steffleupagus/dm-secretary/blob/main/database/questSchema.js): `database/questSchema.js`
- [MongoDB models](https://github.com/steffleupagus/dm-secretary/tree/main/database): `database`

### Other components

- **Discord users**
- **Discord API**
- **MongoDB**

## Connections

- Discord users → Discord API: sends interactions
- Discord API → Event handlers: dispatches events
- Bot loader → Event handlers: registers (evidence: `bot.js`)
- Bot loader → Command handlers: loads commands (evidence: `bot.js`)
- Bot loader → Message handlers: loads handlers (evidence: `bot.js`)
- Bot loader → Health dashboard: can enable (evidence: `bot.js`)
- Event handlers → Command handlers: routes interactions (evidence: `handlers/events/interactionCreate.js`)
- Event handlers → Message handlers: dispatches messages
- Command handlers → Guild roles: handles guild commands
- Command handlers → Table management: handles table commands
- Command handlers → Scene workflow: invokes scene logic
- Command handlers → Travel commands: handles travel
- Message handlers → Quest parser: dispatches quest messages
- Quest parser → Quest records: updates records (evidence: `handlers/message/questMsg.js`)
- Quest parser → Discord API: adds reactions (evidence: `handlers/message/questMsg.js`)
- Table management → Table operations: awards table (evidence: `handlers/commands/cmd_Table.js`)
- Table management → MongoDB models: stores table data
- Activity updater → MongoDB models: reads activity metadata (evidence: `handlers/timers/activityUpdate.js`)
- Activity updater → Discord API: updates channel embeds (evidence: `handlers/timers/activityUpdate.js`)
- Health dashboard → MongoDB: checks connection (evidence: `dashboard/index.js`)
- Bot loader → MongoDB: connects (evidence: `bot.js`)
- Quest records → MongoDB: persists records (evidence: `database/questSchema.js`)
- MongoDB models → MongoDB: defines models