Introduction to TrackerBot
Relevant source files
The following files were used as context for generating this wiki page:
TrackerBot is a dual-service application designed as a companion for the TarkovTracker.org community. It consists of a Discord bot built with discord.js v14 and an Express-based web server. The project provides automated community management, such as ticketing and anti-spam measures, alongside a public intake portal that translates web form submissions directly into GitHub issues for development and data tracking.
The system is built using ECMAScript Modules (ESM) and requires Node.js 18 or higher. It centralizes configuration through environment variables and implements a modular architecture where event-driven handlers and interaction logic are separated from the main entry points.
Sources: AGENTS.md:3-7, README.md:16-24, package.json:6-10
System Architecture
TrackerBot operates two primary services side-by-side. These services can be started concurrently using npm start.
High-Level Component Flow
The following diagram illustrates how the two services interact with external platforms like Discord and GitHub.
The application architecture separates the bot logic into handlers and interaction modules, while the web server serves static files from the /web directory and handles API requests.
Sources: AGENTS.md:12-25, README.md:28-34, webserver.js:77-79
Service Responsibilities
The project is split into two main entry points, each handling specific domain logic.
| Service | File | Primary Responsibilities |
|---|---|---|
| Discord Bot | bot.js | Slash commands, reaction roles, welcome automation, ticketing, and anti-spam (Honeypot). |
| Web Server | webserver.js | Serving public bug/data intake forms and forwarding reports to GitHub. |
Sources: README.md:18-24, AGENTS.md:5-9
1. Discord Bot (bot.js)
The bot initializes by validating environment variables, creating a Discord client with specific intents (Guilds, Members, Messages, Content), and registering handlers for interactions and member events.
- Slash Commands: Includes administrative tools like
/wipeand/nuke, and utility commands like/archiveand/faq1. - Member Handlers: Manages
GuildMemberAddandGuildMemberRemoveevents to assign auto-roles and manage welcome messages. - Honeypot System: A specialized handler (
setupHoneypot) that monitors a hidden channel and automatically bans users who post in it to mitigate spam bots.
Sources: bot.js:10-28, src/client/createClient.js:3-13, src/handlers/memberHandlers.js:14-20, src/handlers/honeypotHandler.js:23-28
2. Web Intake Server (webserver.js)
The web server provides a bridge between the community and the development team. It uses Express to serve forms located in the /web directory and exposes POST endpoints that interact with the GitHub API.
- Issue Routing: Requests to
/issueare routed to the development repository (REPO_DEV), while/datarequests go to the data repository (REPO_DATA_REPORT). - Security: Implements rate limiting via
express-rate-limit, origin validation via an allowlist, and a honeypot field check to prevent automated spam.
Sources: webserver.js:17-45, webserver.js:144-180, webserver.js:185-211
Data Flow: Issue Submission
The web server facilitates a specific flow for converting user input into GitHub issues.
The server truncates fields to specific limits (e.g., Title: 200 chars, Description: 8000 chars) before submission to ensure API compatibility.
Sources: webserver.js:51-60, webserver.js:144-160, webserver.js:185-200
Configuration and Environment
TrackerBot requires strict environment variable validation before startup. This is handled by a central configuration utility.
Required Environment Variables
| Variable | Description | Source |
|---|---|---|
DISCORD_TOKEN | Authentication token for the Discord bot. | src/config/env.js |
ADMIN_ROLE_ID | Comma-separated IDs for administrative roles. | src/config/constants.js |
GITHUB_TOKEN | Personal Access Token for GitHub API access. | webserver.js |
WELCOME_CHANNEL_ID | Channel ID for automated welcome posts. | src/handlers/memberHandlers.js |
REPO_DEV | Target repository for website bug reports. | webserver.js |
Sources: src/config/env.js:5-15, webserver.js:19-21, src/config/constants.js:14-19
Anti-Spam (Honeypot) Logic
The Honeypot system is a critical security feature. It operates by creating an environment where real users are warned not to interact, but bots often trigger the trap.
- Setup: On
ClientReady, the bot ensures a warning message exists in the designated honeypot channel. - Detection: The
MessageCreateevent listens specifically for that channel. It ignores bots and users with theAdminrole. - Action: If triggered, the bot deletes the message and attempts to ban the author. If a ban fails (e.g., due to hierarchy), it falls back to a kick.
- Maintenance: An hourly cleanup task deletes messages older than 16 hours to keep the channel clean while preserving the warning message.
Sources: src/handlers/honeypotHandler.js:23-45, src/handlers/honeypotHandler.js:132-151
Conclusion
TrackerBot serves as a comprehensive bridge between the TarkovTracker.org community and its technical infrastructure. By combining Discord automation with a dedicated web intake server, it streamlines community management and issue reporting while maintaining security through automated moderation and validation systems.