realchriss/bladebot

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.