Dual Service Architecture
Relevant source files
The following files were used as context for generating this wiki page:
TrackerBot utilizes a dual-service architecture designed to handle distinct operational requirements: a real-time Discord interface and a public web portal for issue reporting. These two services run side-by-side as separate processes within a single repository, sharing a common environment configuration and utility base.
The architecture ensures separation of concerns between community management (via the Discord Bot) and data/bug intake (via the Web Server), allowing each to be scaled or maintained independently while contributing to the same GitHub-centric workflow.
Sources: AGENTS.md:7-12, README.md:20-25
Core Service Components
The project is split into two primary entry points that can be executed concurrently using the concurrently package.
| Service | Entry Point | Primary Technology | Responsibility |
|---|---|---|---|
| Discord Bot | bot.js | discord.js v14 | Slash commands, ticketing, moderation, and role automation. |
| Web Server | webserver.js | Express.js | Public issue/data forms and GitHub issue forwarding. |
Sources: package.json:8-12, README.md:21-25, AGENTS.md:8-12
Process Orchestration
The services are managed through NPM scripts defined in package.json. While they can be run individually for debugging, the production-ready npm start command launches both in parallel.
# Start both services
npm start
# Individual service starts
npm run start:bot
npm run start:web
Sources: package.json:8-11, README.md:73-77
Service Interaction and Data Flow
The following diagram illustrates how the two services operate within the environment and interact with external APIs (Discord and GitHub).
The services share logic for environment validation and shared utilities but maintain independent connections to their respective external platforms.
Sources: AGENTS.md:14-25, webserver.js:145-188, bot.js:1-29
Service Detail: Discord Bot (bot.js)
The Discord Bot service is responsible for all interactive elements within the Discord guild. It initializes by validating required environment variables before logging into the Discord gateway.
Initialization Sequence
- Environment Validation: Calls
ensureEnvVars()to verifyDISCORD_TOKEN,WELCOME_CHANNEL_ID, and role IDs. - Client Creation: Configures Gateway Intents (Guilds, Members, Messages, MessageContent).
- Handler Registration: Wires up event listeners for interactions, member joins/leaves, and the honeypot system.
- Command Deployment: Registers slash commands with the Discord API on successful login.
Sources: bot.js:10-29, src/config/env.js:1-10, src/client/createClient.js:3-12
Service Detail: Web Server (webserver.js)
The web service is a public-facing Express application designed to ingest bug and data reports. It serves static HTML files from the /web directory and provides POST endpoints for submission.
GitHub Integration and Security
The web server acts as a proxy for the GitHub API, preventing the exposure of the GITHUB_TOKEN to client browsers. It includes several security layers:
- Rate Limiting: Independent quotas for
/dataand/issueendpoints (5 requests per minute). - Origin Validation: Restricts requests to
ALLOWED_ORIGINSdefined in environment variables. - Honeypot Protection: Hidden form fields detect automated bot submissions.
- Data Sanitization: Truncates titles and descriptions to prevent API abuse.
Sources: webserver.js:35-132, webserver.js:145-188
API Endpoints
| Endpoint | Method | Repository Target | Logic |
|---|---|---|---|
/health | GET | N/A | Returns { status: "ok" }. |
/data | POST | REPO_DATA_REPORT | Processes quest/item data issues. |
/issue | POST | REPO_DEV | Processes website/app bug reports. |
Sources: webserver.js:130-188
Shared Configuration Architecture
Despite running as dual services, both components rely on a centralized configuration and validation system located in src/config/.
Sources: src/config/env.js:1-18, AGENTS.md:28-33
Required Environment Variables
| Variable | Used By | Description |
|---|---|---|
DISCORD_TOKEN | Bot | Authentication for Discord. |
GITHUB_TOKEN | Web | Authentication for GitHub API. |
REPO_DEV | Web | GitHub repo for website bugs. |
REPO_DATA_REPORT | Web | GitHub repo for data issues. |
WELCOME_CHANNEL_ID | Bot | Target for join messages. |
Sources: src/config/env.js:1-10, webserver.js:14-22, README.md:43-60
Conclusion
The Dual Service Architecture of TrackerBot provides a robust separation between real-time Discord interaction and web-based reporting. By utilizing shared environment validation and parallel process execution, the system maintains high technical reliability while offering a unified deployment model for the TarkovTracker community.
Sources: AGENTS.md:7-12, README.md:20-25