Discord Bot Architecture
Relevant source files
The following files were used as context for generating this wiki page:
TrackerBot is a Discord.js v14 companion bot designed for the TarkovTracker.org community. Its primary architecture is centered around an event-driven model that handles slash commands, button interactions, member lifecycle events, and automated moderation via a honeypot system. The bot operates as one of two side-by-side services, with bot.js serving as the main entry point for Discord operations.
Sources: AGENTS.md:1-10, bot.js:1-25
Core System Components
The bot is structured into modular segments including client initialization, command registration, and specialized event handlers. The architectural flow follows a strict startup sequence: environment validation, client creation, handler registration, and finally, Discord authentication.
The diagram above illustrates the initialization sequence performed by the bot during startup.
Sources: bot.js:10-25, AGENTS.md:12-25
Client Configuration
The Discord client is configured in src/client/createClient.js with specific Gateway Intents and Partials. It requires access to Guilds, Members, Messages, and Message Content to perform its automated tasks.
| Intent/Partial | Purpose |
|---|---|
Guilds | Basic server access and event monitoring. |
GuildMembers | Tracking member joins/leaves and role assignments. |
GuildMessages | Monitoring message creation for honeypot and moderation. |
MessageContent | Required for reading message text in moderation flows. |
Partials.Channel | Allows handling events in channels not fully cached. |
Sources: src/client/createClient.js:3-13
Interaction Handling
TrackerBot utilizes a centralized interaction handler that discriminates between slash commands and button clicks. All interactions are restricted to guild contexts to prevent crashes related to missing member data in Direct Messages.
Command and Button Logic
Interactions are routed from the main listener in src/handlers/interactionHandler.js to specific sub-handlers.
This sequence shows how the bot dispatches incoming interactions to the appropriate logic modules.
Sources: src/handlers/interactionHandler.js:5-30, src/interactions/slashHandlers.js:13-25
Slash Commands
Commands are defined using the SlashCommandBuilder and registered globally upon the ClientReady event. Admin-level commands like /wipe and /nuke are protected by role-based access control (RBAC).
Sources: src/commands/registerSlashCommands.js:3-30, src/interactions/slashHandlers.js:16-25
Automated Moderation: The Honeypot
The honeypot system is a specialized security module designed to catch and ban spam bots. It monitors a specific hidden channel (defined by HONEYPOT_CHANNEL_ID) and enforces immediate penalties for any non-admin users who post within it.
Honeypot Workflow
- Setup: On
ClientReady, the bot ensures a warning message is present in the honeypot channel. - Monitoring: The
MessageCreatelistener filters for the specific channel. - Validation: It checks if the author is a bot or has an admin role.
- Enforcement: If unauthorized, the message is deleted, and the user is banned (with a kick fallback).
- Cleanup: An hourly sweep deletes messages older than 16 hours to keep the channel clean.
The honeypot logic ensures immediate removal and punishment for unauthorized activity in protected channels.
Sources: src/handlers/honeypotHandler.js:63-80, src/handlers/honeypotHandler.js:137-155
Member Lifecycle and Role Automation
The bot manages new member arrivals and departures through src/handlers/memberHandlers.js. This module automates the initial server experience and maintains channel cleanliness.
Join and Leave Logic
- GuildMemberAdd: Triggered when a user joins. The bot automatically assigns a set of "User" and "Auto" roles (IDs 1-4) defined in environment variables. It also sends a welcome message and tracks the message ID in an in-memory
Map. - GuildMemberRemove: Triggered when a user leaves. The bot retrieves the welcome message ID from the map and deletes the original welcome message to prevent "ghost" pings or clutter.
Sources: src/handlers/memberHandlers.js:12-30, src/handlers/memberHandlers.js:68-85
Summary
TrackerBot's architecture is a modular, event-driven system built on Discord.js v14. By separating concerns into dedicated handlers for interactions, member events, and security features like the honeypot, the system maintains high reliability and ease of configuration via environment variables. The architecture ensures that administrative tools are secured via role checks while providing seamless automation for community management.
Sources: AGENTS.md:12-25, bot.js:1-25