Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
TrackerBot is a dual-service companion for the TarkovTracker.org community, combining a Discord.js v14 bot with an Express-based web server. The project provides automated community management—including slash commands, reaction roles, and ticketing—alongside a public bug and data intake portal that forwards reports directly to GitHub.
Sources: README.md:1-15, AGENTS.md:5-9
System Architecture
The project operates through two parallel services that run side-by-side. The Discord bot (bot.js) handles real-time interactions within Discord, while the web server (webserver.js) handles HTTP requests for issue reporting. Both services utilize a shared configuration and utility structure located in the src/ directory.
Service Overview
| Service | Entry point | Responsibility |
|---|---|---|
| Discord bot | bot.js | Slash commands, reaction roles, welcome automation, and ticket creation. |
| Bug intake web server | webserver.js | Serves public issue forms and forwards submissions to GitHub repositories. |
Sources: README.md:17-23, AGENTS.md:11-25
The following diagram illustrates the initialization flow for the Discord bot service:
Sources: bot.js:10-31, AGENTS.md:13-25
Prerequisites and Installation
The project requires Node.js 18+ and uses ECMAScript Modules (ESM) throughout.
Installation Steps
- Clone the repository.
- Install dependencies using npm:
npm install
Sources: package.json:28-29, README.md:25-33, AGENTS.md:9
Configuration
The bot uses environment variables for all critical configurations, including API tokens and Discord IDs. These are validated centrally to ensure the process does not start with missing required data.
Required Environment Variables
| Variable | Description |
|---|---|
DISCORD_TOKEN | The authentication token for the Discord bot. |
ADMIN_ROLE_ID | Comma-separated role IDs for admin-only commands. |
WELCOME_CHANNEL_ID | Channel ID where join messages are posted. |
GITHUB_TOKEN | Token with repo scope to create GitHub issues. |
REPO_DEV | Target repository for website bug reports. |
REPO_DATA_REPORT | Target repository for in-game data reports. |
AUTO_ROLE_ID_1-4 | Role IDs automatically assigned to new members. |
PANEL_ADMIN_ROLE_ID | Role ID allowed to manage member roles. |
Sources: src/config/env.js:1-10, README.md:35-49
The src/config/env.js file handles the validation logic, throwing an error if mandatory variables are missing during the ensureEnvVars() call in the entry points.
const requiredEnvVars = [
"DISCORD_TOKEN",
"WELCOME_CHANNEL_ID",
"AUTO_ROLE_ID_1",
"AUTO_ROLE_ID_2",
"AUTO_ROLE_ID_3",
"AUTO_ROLE_ID_4",
"PANEL_ADMIN_ROLE_ID",
"ADMIN_ROLE_ID"
];
export function ensureEnvVars(vars = requiredEnvVars) {
vars.forEach(getRequiredEnv);
}
Sources: src/config/env.js:1-19, bot.js:10
Running the Services
The project uses concurrently to run both services simultaneously for local development, but they can also be started individually.
Execution Commands
- Both services:
npm start - Discord Bot only:
npm run start:bot - Web Server only:
npm run start:web(Default port: 3000)
Sources: package.json:8-11, README.md:53-65
Web Server and Issue Intake
The web server serves static files from the web/ directory and exposes API endpoints for GitHub issue creation. It includes security measures such as rate limiting and an origin allowlist.
API Flow for Issue Submission
The following sequence diagram shows the process of a user submitting a bug report via the web forms:
Sources: webserver.js:124-199, webserver.js:46-77
Security and Middleware
- Trust Proxy: Configured for operation behind reverse proxies (Nginx/Cloudflare) to ensure accurate rate limiting.
- Field Caps: Truncates input fields to prevent oversized payloads (e.g., Title: 200 chars, Description: 8000 chars).
- Honeypot: A hidden
companyfield in the HTML forms detects bot submissions.
Sources: webserver.js:35-44, webserver.js:55-66, webserver.js:118-121
Development and Verification
Before submitting changes, developers should verify their work using the following commands:
npm test: Runs Node.js internal tests (e.g., environment validation tests).node --check bot.js: Performs a syntax check on the entry point.
The architecture follows an event-driven handler pattern where src/handlers/ exports registration functions that attach listeners to the Discord client.
Sources: AGENTS.md:27-35, package.json:7