Web Server Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Web Server within TrackerBot is a standalone Express-based service designed to provide a public interface for reporting bugs and data issues. While the Discord bot handles community interactions, the web server acts as a gateway for intake forms that automatically forward submissions to specific GitHub repositories as issues.
The server is built using Node.js 18+ and leverages Express for routing, Axios for GitHub API communication, and specialized middleware for security, including rate limiting and honeypot validation. It serves static HTML files for the front-end forms and exposes RESTful endpoints for submission processing.
Sources: AGENTS.md:7-10, webserver.js:13-17, README.md:14-19
Core Components and Technologies
The web server architecture is comprised of several distinct layers and dependencies:
| Component | Technology/Implementation | Description |
|---|---|---|
| Runtime | Node.js 18+ | JavaScript runtime for executing the server. |
| Framework | Express 5.x | Web framework for routing and middleware. |
| API Client | Axios | Used to transmit reports to the GitHub API. |
| Rate Limiting | express-rate-limit | Protects endpoints from spam and abuse. |
| Environment | dotenv | Manages configuration via environment variables. |
| Frontend | Static HTML/CSS | Located in the /web directory; provides the UI for users. |
Sources: package.json:26-30, webserver.js:1-9, AGENTS.md:12-25
Service Startup and Parallel Execution
The project uses concurrently to run the Discord bot (bot.js) and the web server (webserver.js) side-by-side. The web server listens on a configurable PORT (defaulting to 3000) and requires environment validation before initialization.
Request Processing and Security
The web server implements multiple layers of security to prevent unauthorized access and bot spam.
Security Pipeline
Every request to the submission endpoints passes through a sequence of checks:
- Trust Proxy: The server is configured to
trust proxy 1to correctly identify client IPs behind reverse proxies for accurate rate limiting. - Rate Limiting: Independent limiters (
dataLimiterandissueLimiter) allow a maximum of 5 submissions per minute per IP. - Origin Validation: The
checkOriginmiddleware verifies theoriginorrefererheaders against anALLOWED_ORIGINSallowlist. - Honeypot Validation: A hidden form field
companyis used to detect automated bot submissions. If filled, the request is silently ignored (returned as successful but not processed).
Sources: webserver.js:46-48, webserver.js:68-76, webserver.js:84-105, webserver.js:123-127
Data Sanitization
Before transmission to GitHub, the server truncates input fields to predefined maximum lengths to prevent injection or overflow issues.
| Field | Max Length | Source |
|---|---|---|
| Title | 200 | webserver.js:55 |
| Discord Handle | 64 | webserver.js:56 |
| Category | 64 | webserver.js:57 |
| Reference | 500 | webserver.js:58 |
| Description | 8000 | webserver.js:59 |
API Endpoints and Integration
The server provides two primary intake routes that map to different GitHub repositories.
Route Overview
Both routes utilize GITHUB_HEADERS for authentication, which includes a GITHUB_TOKEN from the environment.
1. Data Reports (/data)
Submissions to this endpoint are routed to the REPO_DATA_REPORT repository. This is used for quest data, item stats, and map issues.
- Source: web/data/index.html
- Server Logic: webserver.js:137-175
2. Website Issues (/issue)
Submissions to this endpoint are routed to the REPO_DEV repository. This is used for bugs related to the website experience.
- Source: web/issue/index.html
- Server Logic: webserver.js:180-205
Error Handling and Logging
The web server includes a specialized logSanitizedError function. This is critical for security because standard Axios error objects may contain the Authorization header, which would leak the GITHUB_TOKEN into the application logs.
function logSanitizedError(route, err) {
const status = err.response?.status ?? "no-response";
const message = err.message ?? "unknown error";
console.error(`[${route}] GitHub API error: status=${status} message=${message}`);
}
Sources: webserver.js:207-210, webserver.js:172, webserver.js:202
Static File Serving
The server serves static assets from the /web directory using express.static. The directory structure includes specialized forms for different report types:
web/index.html: Main portal with links to both forms.web/issue/index.html: Form for reporting site bugs.web/data/index.html: Form for reporting dataset errors.web/styles.css: Centralized EFT-themed styling.
Sources: webserver.js:115, web/index.html, web/issue/index.html, web/data/index.html
Summary
The TrackerBot Web Server Architecture is a security-focused intake system. By combining Express middleware (rate limiting, origin checking) with client-side honeypots and server-side data sanitization, it provides a robust way for the community to contribute to the project's data and software quality via GitHub issues without requiring direct access to the repositories or exposing the bot's internal infrastructure.