AI Agent Code Guidance

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• bot.js
• webserver.js
• src/config/env.js
• src/config/constants.js
• src/handlers/honeypotHandler.js

TrackerBot is a dual-service application designed as a companion for TarkovTracker.org. It consists of a Discord bot (built with Discord.js v14) and an Express-based web server. The project utilizes ECMAScript Modules (ESM) and requires Node.js 18 or higher.

The codebase is structured to separate concerns between Discord interactions, automated moderation handlers, and public issue intake forms that interface with GitHub APIs.

Sources: AGENTS.md:1-10, README.md:17-25, package.json:6-14

Project Architecture

The application runs two services side-by-side. The Discord bot (bot.js) manages slash commands, reaction roles, and ticketing. The web server (webserver.js) serves static HTML forms and processes POST requests to create GitHub issues.

Component Overview

Component	Path	Description
Bot Entry	bot.js	Validates environment, initializes client, and registers handlers.
Web Entry	webserver.js	Express server for bug and data report intake.
Client	src/client/	Discord client setup including Intents and Partials.
Commands	src/commands/	Slash command definitions and execution logic.
Config	src/config/	Environment validation and constant derivations.
Handlers	src/handlers/	Event-driven logic (Member joins, Honeypot).
Interactions	src/interactions/	Logic for slash commands and button presses.

Sources: AGENTS.md:12-25, README.md:104-114

System Data Flow

The following diagram illustrates the initialization flow and service separation.

Coding Conventions and Standards

Environment Configuration

All required environment variables must be registered in src/config/env.js. New variables must also be added to .env.example. Optional features should read variables defensively to avoid breaking the test suite or deployments.

Sources: src/config/env.js:1-15, AGENTS.md:29-33

Handler Registration

Handlers must export a registerXxxHandlers(client) or setupXxx(client) function. These functions attach event listeners to the Discord client and are wired up centrally in bot.js.

Sources: bot.js:22-24, AGENTS.md:27-28

Error Handling

Errors should be caught at handler boundaries and logged via console.error or console.warn. The process should never be allowed to crash. Specifically, when interacting with the GitHub API, sensitive information like Authorization headers must be stripped from logs.

Sources: webserver.js:154-162, AGENTS.md:36

Feature Implementation Logic

Honeypot Anti-Spam

The honeypot feature uses a hidden channel to trap and ban bots. It operates on a specific logic to ensure administrators are exempt and messages are periodically cleaned.

Web-to-GitHub Issue Intake

The web server validates incoming reports before forwarding them to GitHub. It implements rate limiting and a client-side honeypot field to prevent automated spam.

• Rate Limiting: 5 submissions per minute per IP.
• Validation: Truncates fields (e.g., Title: 200 chars, Description: 8000 chars).
• GitHub Integration: Uses axios to post to repositories defined in REPO_DEV and REPO_DATA_REPORT.

Sources: webserver.js:46-60, webserver.js:74-80, webserver.js:126-152

Verification and Testing

Before finalizing code changes, the following checks are mandatory:

1. Unit Tests: Run npm test to execute Node --test files (primarily for environment and command logic validation).
2. Syntax Checks: Run node --check bot.js and node --check webserver.js.
3. CI Consistency: The GitHub Actions workflow performs npm ci followed by a recursive syntax check on all .js files.

Sources: package.json:7-11, AGENTS.md:41-47

Summary

TrackerBot is a modular companion tool for the TarkovTracker community. Developers and AI agents must strictly adhere to the established architecture—separating the Express web server from the Discord bot logic—while ensuring all new configuration is validated through the centralized env.js utility and protected by appropriate error handling.

Sources: AGENTS.md:5-9, README.md:17-25