# codebymitch/titanbot architecture

> Architecture diagram of the GitHub repository codebymitch/titanbot, 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/codebymitch/titanbot
- Repository: https://github.com/codebymitch/titanbot

## Overview

TitanBot is a Discord server-management and community bot. A typical flow begins with a server member or moderator issuing a command or interacting with a component; Discord events and the interaction router dispatch to feature commands/services, which perform domain actions and persist guild-scoped state before responding in Discord. The README also documents broad feature families beyond the sampled implementation. The graph includes those feature branches, while edges are limited to relationships shown in excerpts, SOURCE INDEX references, or README statements; unsampled feature internals are represented at their existing directories.

Main entry points: [`src/commands`](https://github.com/codebymitch/titanbot/tree/main/src/commands) (Command catalog), [`src/app.js`](https://github.com/codebymitch/titanbot/blob/main/src/app.js) (Bot application), [`src/events/interactionCreate.js`](https://github.com/codebymitch/titanbot/blob/main/src/events/interactionCreate.js) (Interaction routing), [`src/events`](https://github.com/codebymitch/titanbot/tree/main/src/events) (Discord event handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_app["Bot application<br/>[app.js]"]
  node_events["Discord event handlers"]
  node_commands["Command catalog"]
  node_interactions["Component interactions"]
  node_interactionrouter["Interaction routing"]
end

subgraph group_community["Community Features"]
  node_tickets["Ticket workflows<br/>[ticket.js]"]
  node_applications["Community applications"]
  node_reactionroles["Reaction roles"]
  node_jointocreate["Join-to-create voice"]
  node_serverstats["Server counters"]
  node_music["Music playback<br/>[playerHandler.js]"]
  node_utility["Utility and search"]
end

subgraph group_governance["Server Administration"]
  node_moderation["Moderation actions"]
  node_logging["Audit logging<br/>[loggingService.js]"]
  node_verification["Member verification"]
  node_config["Guild configuration<br/>[guildConfig.js]"]
end

subgraph group_engagement["Engagement Features"]
  node_economy["Economy and shop"]
  node_leveling["XP and level roles<br/>[leveling.js]"]
  node_giveaways["Giveaways<br/>[giveawayService.js]"]
  node_birthdays["Birthday tracking<br/>[birthdayService.js]"]
  node_welcome["Welcome and auto roles"]
end

subgraph group_platform["Shared Platform"]
  node_database["Database facade<br/>[database.js]"]
  node_guildstorage["Guild config storage"]
  node_postgres[("PostgreSQL store")]
  node_configsource["Application configuration<br/>[application.js]"]
  node_logger["Structured logging<br/>[logger.js]"]
  node_responses["Interaction responses"]
  node_errors["Error handling<br/>[errorHandler.js]"]
end

node_member(("Discord users"))
node_moderator(("Server moderators"))
node_discord{{"Discord API"}}

node_member -->|"issues commands"| node_discord
node_moderator -->|"manages server"| node_discord
node_discord -.->|"sends events"| node_events
node_app -->|"initializes database"| node_database
node_app -->|"loads commands"| node_commands
node_app -->|"updates counters"| node_serverstats
node_events -.->|"routes interactions"| node_interactionrouter
node_interactionrouter -->|"dispatches command"| node_applications
node_interactionrouter -->|"dispatches interaction"| node_reactionroles
node_interactionrouter -->|"uses responses"| node_responses
node_interactionrouter -->|"routes failures"| node_errors
node_commands -.->|"provides commands"| node_moderation
node_moderation -.->|"records actions"| node_logging
node_commands -->|"provides commands"| node_economy
node_commands -->|"provides commands"| node_leveling
node_commands -->|"provides commands"| node_giveaways
node_commands -->|"provides commands"| node_birthdays
node_events -.->|"handles member joins"| node_welcome
node_commands -->|"provides commands"| node_tickets
node_commands -->|"dispatches application"| node_applications
node_commands -.->|"configures roles"| node_reactionroles
node_events -.->|"handles voice changes"| node_jointocreate
node_app -->|"reads and refreshes"| node_serverstats
node_commands -->|"provides controls"| node_music
node_commands -->|"provides tools"| node_utility
node_app -->|"loads configuration"| node_configsource
node_config -->|"reads and writes"| node_guildstorage
node_guildstorage -->|"reads and writes"| node_database
node_database -->|"uses backend"| node_postgres
node_app -->|"logs startup"| node_logger
node_responses -->|"handles failures"| node_errors
node_discord -.->|"provides voice playback"| node_music

click node_app "https://github.com/codebymitch/titanbot/blob/main/src/app.js"
click node_events "https://github.com/codebymitch/titanbot/tree/main/src/events"
click node_commands "https://github.com/codebymitch/titanbot/tree/main/src/commands"
click node_interactions "https://github.com/codebymitch/titanbot/tree/main/src/interactions"
click node_moderation "https://github.com/codebymitch/titanbot/tree/main/src/commands/Moderation"
click node_logging "https://github.com/codebymitch/titanbot/blob/main/src/services/loggingService.js"
click node_verification "https://github.com/codebymitch/titanbot/blob/main/src/services/verificationService.js"
click node_config "https://github.com/codebymitch/titanbot/blob/main/src/services/config/guildConfig.js"
click node_economy "https://github.com/codebymitch/titanbot/tree/main/src/commands/Economy"
click node_leveling "https://github.com/codebymitch/titanbot/blob/main/src/services/leveling/leveling.js"
click node_giveaways "https://github.com/codebymitch/titanbot/blob/main/src/services/giveawayService.js"
click node_birthdays "https://github.com/codebymitch/titanbot/blob/main/src/services/birthdayService.js"
click node_welcome "https://github.com/codebymitch/titanbot/tree/main/src/commands/Welcome"
click node_tickets "https://github.com/codebymitch/titanbot/blob/main/src/services/ticket.js"
click node_applications "https://github.com/codebymitch/titanbot/blob/main/src/services/applicationService.js"
click node_reactionroles "https://github.com/codebymitch/titanbot/blob/main/src/services/reactionRoleService.js"
click node_jointocreate "https://github.com/codebymitch/titanbot/blob/main/src/services/joinToCreateService.js"
click node_serverstats "https://github.com/codebymitch/titanbot/blob/main/src/services/serverstatsService.js"
click node_music "https://github.com/codebymitch/titanbot/blob/main/src/services/music/playerHandler.js"
click node_utility "https://github.com/codebymitch/titanbot/tree/main/src/commands/Utility"
click node_database "https://github.com/codebymitch/titanbot/blob/main/src/utils/database.js"
click node_guildstorage "https://github.com/codebymitch/titanbot/blob/main/src/utils/database/guildConfigStorage.js"
click node_postgres "https://github.com/codebymitch/titanbot/blob/main/src/utils/postgresDatabase.js"
click node_configsource "https://github.com/codebymitch/titanbot/blob/main/src/config/application.js"
click node_interactionrouter "https://github.com/codebymitch/titanbot/blob/main/src/events/interactionCreate.js"
click node_logger "https://github.com/codebymitch/titanbot/blob/main/src/utils/logger.js"
click node_responses "https://github.com/codebymitch/titanbot/blob/main/src/utils/interactionHelper.js"
click node_errors "https://github.com/codebymitch/titanbot/blob/main/src/utils/errorHandler.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_app,node_events,node_commands,node_interactions,node_interactionrouter,node_member toneBlue
class node_tickets,node_applications,node_reactionroles,node_jointocreate,node_serverstats,node_music,node_utility toneAmber
class node_moderation,node_logging,node_verification,node_config,node_moderator,node_discord toneMint
class node_economy,node_leveling,node_giveaways,node_birthdays,node_welcome toneRose
class node_database,node_guildstorage,node_postgres,node_configsource,node_logger,node_responses,node_errors toneIndigo
```

## Components

### Bot Runtime

- [Bot application](https://github.com/codebymitch/titanbot/blob/main/src/app.js): `src/app.js`
- [Discord event handlers](https://github.com/codebymitch/titanbot/tree/main/src/events): `src/events`
- [Command catalog](https://github.com/codebymitch/titanbot/tree/main/src/commands): `src/commands`
- [Component interactions](https://github.com/codebymitch/titanbot/tree/main/src/interactions): `src/interactions`
- [Interaction routing](https://github.com/codebymitch/titanbot/blob/main/src/events/interactionCreate.js): `src/events/interactionCreate.js`

### Community Features

- [Ticket workflows](https://github.com/codebymitch/titanbot/blob/main/src/services/ticket.js): `src/services/ticket.js`
- [Community applications](https://github.com/codebymitch/titanbot/blob/main/src/services/applicationService.js): `src/services/applicationService.js`
- [Reaction roles](https://github.com/codebymitch/titanbot/blob/main/src/services/reactionRoleService.js): `src/services/reactionRoleService.js`
- [Join-to-create voice](https://github.com/codebymitch/titanbot/blob/main/src/services/joinToCreateService.js): `src/services/joinToCreateService.js`
- [Server counters](https://github.com/codebymitch/titanbot/blob/main/src/services/serverstatsService.js): `src/services/serverstatsService.js`
- [Music playback](https://github.com/codebymitch/titanbot/blob/main/src/services/music/playerHandler.js): `src/services/music/playerHandler.js`
- [Utility and search](https://github.com/codebymitch/titanbot/tree/main/src/commands/Utility): `src/commands/Utility`

### Server Administration

- [Moderation actions](https://github.com/codebymitch/titanbot/tree/main/src/commands/Moderation): `src/commands/Moderation`
- [Audit logging](https://github.com/codebymitch/titanbot/blob/main/src/services/loggingService.js): `src/services/loggingService.js`
- [Member verification](https://github.com/codebymitch/titanbot/blob/main/src/services/verificationService.js): `src/services/verificationService.js`
- [Guild configuration](https://github.com/codebymitch/titanbot/blob/main/src/services/config/guildConfig.js): `src/services/config/guildConfig.js`

### Engagement Features

- [Economy and shop](https://github.com/codebymitch/titanbot/tree/main/src/commands/Economy): `src/commands/Economy`
- [XP and level roles](https://github.com/codebymitch/titanbot/blob/main/src/services/leveling/leveling.js): `src/services/leveling/leveling.js`
- [Giveaways](https://github.com/codebymitch/titanbot/blob/main/src/services/giveawayService.js): `src/services/giveawayService.js`
- [Birthday tracking](https://github.com/codebymitch/titanbot/blob/main/src/services/birthdayService.js): `src/services/birthdayService.js`
- [Welcome and auto roles](https://github.com/codebymitch/titanbot/tree/main/src/commands/Welcome): `src/commands/Welcome`

### Shared Platform

- [Database facade](https://github.com/codebymitch/titanbot/blob/main/src/utils/database.js): `src/utils/database.js`
- [Guild config storage](https://github.com/codebymitch/titanbot/blob/main/src/utils/database/guildConfigStorage.js): `src/utils/database/guildConfigStorage.js`
- [PostgreSQL store](https://github.com/codebymitch/titanbot/blob/main/src/utils/postgresDatabase.js): `src/utils/postgresDatabase.js`
- [Application configuration](https://github.com/codebymitch/titanbot/blob/main/src/config/application.js): `src/config/application.js`
- [Structured logging](https://github.com/codebymitch/titanbot/blob/main/src/utils/logger.js): `src/utils/logger.js`
- [Interaction responses](https://github.com/codebymitch/titanbot/blob/main/src/utils/interactionHelper.js): `src/utils/interactionHelper.js`
- [Error handling](https://github.com/codebymitch/titanbot/blob/main/src/utils/errorHandler.js): `src/utils/errorHandler.js`

### Other components

- **Discord users**
- **Server moderators**
- **Discord API**

## Connections

- Discord users → Discord API: issues commands
- Server moderators → Discord API: manages server
- Discord API → Discord event handlers: sends events
- Bot application → Database facade: initializes database (evidence: `src/app.js`)
- Bot application → Command catalog: loads commands (evidence: `src/app.js`)
- Bot application → Server counters: updates counters (evidence: `src/app.js`)
- Discord event handlers → Interaction routing: routes interactions
- Interaction routing → Community applications: dispatches command (evidence: `src/events/interactionCreate.js`)
- Interaction routing → Reaction roles: dispatches interaction (evidence: `src/events/interactionCreate.js`)
- Interaction routing → Interaction responses: uses responses (evidence: `src/events/interactionCreate.js`)
- Interaction routing → Error handling: routes failures (evidence: `src/events/interactionCreate.js`)
- Command catalog → Moderation actions: provides commands
- Moderation actions → Audit logging: records actions
- Command catalog → Economy and shop: provides commands
- Command catalog → XP and level roles: provides commands
- Command catalog → Giveaways: provides commands
- Command catalog → Birthday tracking: provides commands
- Discord event handlers → Welcome and auto roles: handles member joins
- Command catalog → Ticket workflows: provides commands
- Command catalog → Community applications: dispatches application (evidence: `src/commands/Community/apply.js`)
- Command catalog → Reaction roles: configures roles
- Discord event handlers → Join-to-create voice: handles voice changes
- Bot application → Server counters: reads and refreshes (evidence: `src/app.js`)
- Command catalog → Music playback: provides controls
- Command catalog → Utility and search: provides tools
- Bot application → Application configuration: loads configuration (evidence: `src/app.js`)
- Guild configuration → Guild config storage: reads and writes (evidence: `src/services/config/guildConfig.js`)
- Guild config storage → Database facade: reads and writes (evidence: `src/utils/database/guildConfigStorage.js`)
- Database facade → PostgreSQL store: uses backend (evidence: `src/utils/database.js`)
- Bot application → Structured logging: logs startup (evidence: `src/app.js`)
- Interaction responses → Error handling: handles failures (evidence: `src/utils/interactionHelper.js`)
- Discord API → Music playback: provides voice playback