# realchriss/bladebot architecture

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

- Interactive diagram: https://gitdiagram.com/realchriss/bladebot
- Repository: https://github.com/realchriss/bladebot

## Overview

1. **Overall shape**
   BladeBot is a Node.js/TypeScript Discord bot. Its architecture is centered on a Discord client that receives events and slash commands, then routes them into feature-specific handlers. Most business state is persisted in a relational database through Prisma.

2. **Bootstrap and runtime**
   `src/index.ts` and `src/bot/run.ts` are the entry path into the bot process. Startup loads environment config, initializes logging, connects to the database, creates the Discord client, and registers command/event handlers before the bot begins processing Discord traffic.

3. **Discord integration boundary**
   The bot’s main external boundary is the Discord API via `discord.js`. Everything under `src/bot/` is organized around Discord interaction types: slash commands, gateway events, message/embed sending, and modal submissions. This is the primary ingress/egress path for the system.

4. **Command subsystem**
   `src/bot/slash/` contains the user-facing slash commands such as ping, help, settings, application viewing/listing, statistics, warns, changelog, and Roblox-related stats. `slashHandler.ts` and `cmdHandler.ts` provide discovery/routing so commands are loaded as discrete modules rather than hardcoded in one place.

5. **Event-driven workflow**
   `src/bot/events/` contains the operational workflows that happen after Discord interactions or server events. Examples include application acceptance/rejection, verify-and-waitlist behavior, invite confirmation, user leave notifications, and application cleanup on leave. These handlers are where the bot reacts to state changes and drives follow-up actions.

6. **Application management pipeline**
   Application flow is one of the core subsystems. Users open and submit application modals, the bot validates the submission, stores application records, and moderators can review them via commands or event-driven actions. Acceptance/rejection then triggers downstream effects like role assignment, status updates, notifications, and invite handling.

7. **Warns and member notifications**
   The warnings subsystem tracks AP and donation warnings, supports listing/removal, and notifies members directly by DM with channel fallback when needed. Utility modules like `warnUtils.ts` encapsulate the warning-specific logic, while event handlers coordinate member-facing notifications.

8. **Persistence layer**
   `src/db/prisma.ts` is the database access boundary, backed by `prisma/schema.prisma` and `prisma/seed.js`. The database stores application records, warnings, settings, and related server state so the bot can recover after restarts and support moderation workflows across sessions.

9. **Ephemeral UI state**
   `src/bot/stores/` holds in-memory state for interactive modals such as application and eval flows. This is separate from the database because these are short-lived interaction contexts tied to Discord component lifecycles rather than durable business records.

10. **Shared utilities and presentation**
    `src/utils/` contains cross-cutting services: configuration loading, logging, application statistics, chart generation, string normalization, build info, and application action helpers. `src/bot/assets/emoji.ts` maps custom emojis used across embeds and responses, making presentation consistent across commands and events.

11. **Deployment model**
    The repo is built for containerized deployment with Docker and compose files, plus shell scripts for start/stop/restart lifecycle management. This suggests a long-running bot service rather than a request/response app, with environment-driven configuration and externalized secrets per deployment.

12. **External services**
    Besides Discord, the bot integrates with Roblox-related data for application validation and statistics. That makes Roblox an important external dependency for the application and profile-checking flows, while Discord remains the transport and user interface layer.

Main entry points: [`src/bot/run.ts`](https://github.com/realchriss/bladebot/blob/main/src/bot/run.ts) (Run bot), [`src/bot/cmdHandler.ts`](https://github.com/realchriss/bladebot/blob/main/src/bot/cmdHandler.ts) (Command router), [`src/bot/eventHandler.ts`](https://github.com/realchriss/bladebot/blob/main/src/bot/eventHandler.ts) (Event router), [`src/db/prisma.ts`](https://github.com/realchriss/bladebot/blob/main/src/db/prisma.ts) (Prisma DB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_boot["Bootstrap"]
  node_n_index["Entry<br/>[index.ts]"]
  node_n_run["Run bot<br/>startup<br/>[run.ts]"]
end

subgraph group_g_discord["Discord boundary"]
  node_n_client["Discord client<br/>[client.ts]"]
  node_n_cmdhandler["Command router<br/>slash router<br/>[cmdHandler.ts]"]
  node_n_eventhandler["Event router<br/>[eventHandler.ts]"]
  node_n_slashbase["Command types<br/>base classes<br/>[ClientSlash.ts]"]
  node_n_eventbase["Event types<br/>base classes<br/>[ClientEvent.ts]"]
  node_n_message["Message sender<br/>discord helper<br/>[MessageSender.ts]"]
end

subgraph group_g_workflows["Workflows"]
  node_n_applycmd["Applications<br/>slash feature"]
  node_n_moderation["Moderation<br/>slash feature<br/>[warn.ts]"]
  node_n_info["Info cmds<br/>slash feature<br/>[help.ts]"]
  node_n_eventapps["App events<br/>workflow events"]
  node_n_eventmodals["Modal flows<br/>interaction events<br/>[applyModalOpen.ts]"]
  node_n_notifications["Member alerts<br/>notification events<br/>[userLeaveNotify.ts]"]
end

subgraph group_g_data["State & persistence"]
  node_n_db[("Prisma DB<br/>persistence<br/>[prisma.ts]")]
  node_n_schema["Schema<br/>[schema.prisma]"]
  node_n_stores["Modal store<br/>ephemeral state<br/>[applyModalStore.ts]"]
end

subgraph group_g_shared["Shared services"]
  node_n_utils["Shared utils<br/>cross-cutting utils<br/>[ConfigManager.ts]"]
  node_n_emojis["Emoji map<br/>presentation<br/>[emoji.ts]"]
end

subgraph group_g_deploy["Deployment"]
  node_n_deploy["Deploy scripts<br/>ops scripts<br/>[start.sh]"]
end

node_n_index -->|"starts"| node_n_run
node_n_run -->|"creates"| node_n_client
node_n_run -->|"registers"| node_n_cmdhandler
node_n_run -->|"registers"| node_n_eventhandler
node_n_run -->|"connects"| node_n_db
node_n_run -->|"uses"| node_n_utils
node_n_cmdhandler -->|"loads"| node_n_slashbase
node_n_eventhandler -->|"loads"| node_n_eventbase
node_n_client -->|"sends via"| node_n_message
node_n_client -->|"routes commands"| node_n_cmdhandler
node_n_client -->|"routes events"| node_n_eventhandler
node_n_cmdhandler -->|"serves"| node_n_applycmd
node_n_cmdhandler -->|"serves"| node_n_moderation
node_n_cmdhandler -->|"serves"| node_n_info
node_n_eventhandler -->|"drives"| node_n_eventapps
node_n_eventhandler -->|"drives"| node_n_eventmodals
node_n_eventhandler -->|"drives"| node_n_notifications
node_n_eventapps -->|"persists"| node_n_db
node_n_eventapps -->|"uses"| node_n_stores
node_n_eventmodals -->|"uses"| node_n_stores
node_n_moderation -->|"reads/writes"| node_n_db
node_n_moderation -->|"uses"| node_n_utils
node_n_info -->|"uses"| node_n_utils
node_n_applycmd -->|"uses"| node_n_utils
node_n_utils -->|"formats"| node_n_emojis
node_n_db -->|"backed by"| node_n_schema
node_n_deploy -->|"launches"| node_n_run
node_n_deploy -.->|"configures"| node_n_db

click node_n_index "https://github.com/realchriss/bladebot/blob/main/src/index.ts"
click node_n_run "https://github.com/realchriss/bladebot/blob/main/src/bot/run.ts"
click node_n_client "https://github.com/realchriss/bladebot/blob/main/src/bot/client.ts"
click node_n_cmdhandler "https://github.com/realchriss/bladebot/blob/main/src/bot/cmdHandler.ts"
click node_n_eventhandler "https://github.com/realchriss/bladebot/blob/main/src/bot/eventHandler.ts"
click node_n_slashbase "https://github.com/realchriss/bladebot/blob/main/src/bot/classes/ClientSlash.ts"
click node_n_eventbase "https://github.com/realchriss/bladebot/blob/main/src/bot/classes/ClientEvent.ts"
click node_n_message "https://github.com/realchriss/bladebot/blob/main/src/bot/classes/MessageSender.ts"
click node_n_applycmd "https://github.com/realchriss/bladebot/blob/main/src/bot/slash/applicationEmbed.ts"
click node_n_moderation "https://github.com/realchriss/bladebot/blob/main/src/bot/slash/warn.ts"
click node_n_info "https://github.com/realchriss/bladebot/blob/main/src/bot/slash/help.ts"
click node_n_eventapps "https://github.com/realchriss/bladebot/blob/main/src/bot/events/applicationAccept.ts"
click node_n_eventmodals "https://github.com/realchriss/bladebot/blob/main/src/bot/events/applyModalOpen.ts"
click node_n_notifications "https://github.com/realchriss/bladebot/blob/main/src/bot/events/userLeaveNotify.ts"
click node_n_db "https://github.com/realchriss/bladebot/blob/main/src/db/prisma.ts"
click node_n_schema "https://github.com/realchriss/bladebot/blob/main/prisma/schema.prisma"
click node_n_stores "https://github.com/realchriss/bladebot/blob/main/src/bot/stores/applyModalStore.ts"
click node_n_utils "https://github.com/realchriss/bladebot/blob/main/src/utils/ConfigManager.ts"
click node_n_emojis "https://github.com/realchriss/bladebot/blob/main/src/bot/assets/emoji.ts"
click node_n_deploy "https://github.com/realchriss/bladebot/blob/main/docker/start.sh"

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_n_index,node_n_run toneBlue
class node_n_client,node_n_cmdhandler,node_n_eventhandler,node_n_slashbase,node_n_eventbase,node_n_message toneAmber
class node_n_applycmd,node_n_moderation,node_n_info,node_n_eventapps,node_n_eventmodals,node_n_notifications toneMint
class node_n_db,node_n_schema,node_n_stores toneRose
class node_n_utils,node_n_emojis toneIndigo
class node_n_deploy toneTeal
```

## Components

### Bootstrap

Process entry, runtime startup, and Discord client wiring.

- [Entry](https://github.com/realchriss/bladebot/blob/main/src/index.ts): ts entry · Top-level process entry that starts the bot runtime. · `src/index.ts`
- [Run bot](https://github.com/realchriss/bladebot/blob/main/src/bot/run.ts): startup · Bootstraps config, logging, database, handlers, and the Discord client. · `src/bot/run.ts`

### Discord boundary

Client-facing Discord integration and command/event routing.

- [Discord client](https://github.com/realchriss/bladebot/blob/main/src/bot/client.ts): discord client · Discord.js client wrapper used to connect to the platform. · `src/bot/client.ts`
- [Command router](https://github.com/realchriss/bladebot/blob/main/src/bot/cmdHandler.ts): slash router · Discovers and dispatches slash commands. · `src/bot/cmdHandler.ts`
- [Event router](https://github.com/realchriss/bladebot/blob/main/src/bot/eventHandler.ts): event router · Loads and dispatches gateway and interaction event handlers. · `src/bot/eventHandler.ts`
- [Command types](https://github.com/realchriss/bladebot/blob/main/src/bot/classes/ClientSlash.ts): base classes · Shared command abstractions used by the command system. · `src/bot/classes/ClientSlash.ts`
- [Event types](https://github.com/realchriss/bladebot/blob/main/src/bot/classes/ClientEvent.ts): base classes · Shared event abstractions used by the event system. · `src/bot/classes/ClientEvent.ts`
- [Message sender](https://github.com/realchriss/bladebot/blob/main/src/bot/classes/MessageSender.ts): discord helper · Shared sending and response helper for Discord output. · `src/bot/classes/MessageSender.ts`

### Workflows

Feature workflows driven by slash commands and gateway events.

- [Applications](https://github.com/realchriss/bladebot/blob/main/src/bot/slash/applicationEmbed.ts): slash feature · Application-facing slash command flow and embeds. · `src/bot/slash/applicationEmbed.ts`
- [Moderation](https://github.com/realchriss/bladebot/blob/main/src/bot/slash/warn.ts): slash feature · Warn and moderation command surface. · `src/bot/slash/warn.ts`
- [Info cmds](https://github.com/realchriss/bladebot/blob/main/src/bot/slash/help.ts): slash feature · Help, ping, settings, changelog, stats, and Roblox stats commands. · `src/bot/slash/help.ts`
- [App events](https://github.com/realchriss/bladebot/blob/main/src/bot/events/applicationAccept.ts): workflow events · Application acceptance, rejection, verification, cleanup, and invite handling. · `src/bot/events/applicationAccept.ts`
- [Modal flows](https://github.com/realchriss/bladebot/blob/main/src/bot/events/applyModalOpen.ts): interaction events · Modal open and submit handlers for application and eval interactions. · `src/bot/events/applyModalOpen.ts`
- [Member alerts](https://github.com/realchriss/bladebot/blob/main/src/bot/events/userLeaveNotify.ts): notification events · Leave and card notification flows sent to members and channels. · `src/bot/events/userLeaveNotify.ts`

### State & persistence

Database access plus short-lived interaction state.

- [Prisma DB](https://github.com/realchriss/bladebot/blob/main/src/db/prisma.ts): persistence · Database access boundary for durable bot state. · `src/db/prisma.ts`
- [Schema](https://github.com/realchriss/bladebot/blob/main/prisma/schema.prisma): prisma schema · Relational schema defining applications, warnings, settings, and related state. · `prisma/schema.prisma`
- [Modal store](https://github.com/realchriss/bladebot/blob/main/src/bot/stores/applyModalStore.ts): ephemeral state · In-memory state for short-lived application and eval modal lifecycles. · `src/bot/stores/applyModalStore.ts`

### Shared services

Cross-cutting utilities and presentation helpers.

- [Shared utils](https://github.com/realchriss/bladebot/blob/main/src/utils/ConfigManager.ts): cross-cutting utils · Config, logging, stats, charts, string normalization, build info, and action helpers. · `src/utils/ConfigManager.ts`
- [Emoji map](https://github.com/realchriss/bladebot/blob/main/src/bot/assets/emoji.ts): presentation · Shared custom emoji definitions used in responses and embeds. · `src/bot/assets/emoji.ts`

### Deployment

Container and lifecycle scripts for operating the bot.

- [Deploy scripts](https://github.com/realchriss/bladebot/blob/main/docker/start.sh): ops scripts · Docker and shell lifecycle scripts for running and restarting the bot. · `docker/start.sh`

## Connections

- Entry → Run bot: starts · Entry point invokes the bot bootstrap.
- Run bot → Discord client: creates · Bootstrap constructs and configures the Discord client.
- Run bot → Command router: registers · Bootstrap loads slash command routing.
- Run bot → Event router: registers · Bootstrap loads event routing.
- Run bot → Prisma DB: connects · Bootstrap initializes database access.
- Run bot → Shared utils: uses · Startup depends on shared config and logging services.
- Command router → Command types: loads · Command router discovers command modules via shared types.
- Event router → Event types: loads · Event router discovers handler modules via shared types.
- Discord client → Message sender: sends via · Client output flows through message helper utilities.
- Discord client → Command router: routes commands · Discord interactions are dispatched to slash commands.
- Discord client → Event router: routes events · Gateway and modal events are dispatched to handlers.
- Command router → Applications: serves · Command routing includes application-related commands.
- Command router → Moderation: serves · Command routing includes moderation commands.
- Command router → Info cmds: serves · Command routing includes informational commands.
- Event router → App events: drives · Event routing executes application lifecycle workflows.
- Event router → Modal flows: drives · Event routing handles modal open and submit flows.
- Event router → Member alerts: drives · Event routing handles user-facing notifications.
- App events → Prisma DB: persists · Application workflows store and update durable records.
- App events → Modal store: uses · Some application interactions depend on ephemeral modal state.
- Modal flows → Modal store: uses · Modal submit flows consult in-memory interaction state.
- Moderation → Prisma DB: reads/writes · Warning commands operate on persistent moderation data.
- Moderation → Shared utils: uses · Warn behavior relies on shared warning and formatting helpers.
- Info cmds → Shared utils: uses · Informational commands reuse shared utilities for stats and formatting.
- Applications → Shared utils: uses · Application views and embeds use shared helpers.
- Shared utils → Emoji map: formats · Shared utilities and responses use common emoji mappings.
- Prisma DB → Schema: backed by · Prisma access is defined by the schema.
- Deploy scripts → Run bot: launches · Deployment scripts start and manage the bot process.
- Deploy scripts → Prisma DB: configures · Runtime deployment expects external database configuration.