How qs-zuq/humanitzbot works
1. System shape
- This is a single Node.js 18+ application that combines a Discord bot, a web dashboard, and a game-server integration layer for HumanitZ dedicated servers.
- The core architectural idea is: external server data flows into a shared SQLite database, and both Discord and the web UI read from that state and trigger actions back toward the game server.
2. Primary runtime entry points
- src/index.js orchestrates the bot runtime and module startup.
- src/web-map/server.js runs a separate Express-based web/API server for the dashboard.
- src/setup.js, src/deploy-commands.js, and src/env-sync.js handle first-run bootstrapping, slash-command registration, and configuration migration.
3. Discord bot plane
- Slash commands live in src/commands/ and cover player lookup, stats, server info, RCON access, panel controls, and thread management.
- The bot-side modules in src/modules/ generate embeds, relay chat, announce milestones, manage status channels, and post activity feeds into Discord.
- Discord is not just a notification sink; it is an operational surface for server management and player-facing telemetry.
4. Game-server integration plane
- The repo talks to the HumanitZ server through multiple channels: SFTP for files/logs/saves, RCON for live server commands, and optionally Pterodactyl Panel API/WebSocket RCON for hosted setups.
- src/rcon/ encapsulates command execution and server info queries.
- src/server/panel-api.js and src/rcon/panel-rcon.js are the managed-hosting boundary, while direct TCP RCON/SFTP supports self-hosted deployments.
5. Data ingestion and parsing pipeline
- src/modules/log-watcher.js tails server logs and feeds parsed events into the activity and chat systems.
- src/parsers/save-parser.js and related parser files decode binary .sav world-state files into structured entities such as players, structures, vehicles, containers, and companions.
- src/parsers/save-service.js and the snapshot service periodically pull game state, enabling historical reconstruction rather than only live state.
6. Persistence as the central backbone
- SQLite, accessed through src/db/database.js, is the main system of record.
- The schema covers player stats, activity logs, chat history, world entities, timelines/snapshots, server settings, and reference game data.
- src/db/config-repository.js, config-migration.js, and config-validation.js show that configuration is stored and migrated in the database, not left purely in .env.
7. Change detection and tracking
- The database layer includes a diff engine and item tracker (src/db/diff-engine.js, item-fingerprint.js, item-tracker.js) that compare consecutive world snapshots.
- Tracking modules in src/tracking/ aggregate derived facts such as playtime, kills, player statistics, and snapshot history.
- This is the core analytics path: raw logs and saves become durable game events, player metrics, and item custody chains.
8. Automation and scheduling
- src/modules/pvp-scheduler.js and src/modules/server-scheduler.js automate server behavior based on time windows and profiles.
- Supporting utilities coordinate countdowns, restart timing, and config changes that may require a server restart.
- Other modules handle recurring behaviors like auto-messages, daily threads, recaps, milestone announcements, and status rotation.
9. Web dashboard architecture
- The dashboard is an Express app with both API endpoints and static frontend assets under src/web-map/public/.
- It exposes public landing pages plus authenticated operational views: map, player list, activity feed, chat history, database browser, admin controls, and settings.
- Discord OAuth2 with role-based access gates the sensitive functionality, so the web tier is both a read model and a control plane.
10. Multi-server boundary
- The project is explicitly multi-server: src/server/multi-server.js manages isolated instances, each with its own config, RCON connection, stats, logs, and scheduler state.
- The shared codebase can supervise multiple game servers, but the data and operational state are partitioned per server in SQLite and in the runtime module set.
- That isolation is important for any architecture diagram: each server is effectively a separate tenant under one bot/dashboard installation.
11. Operational and support layers
- src/utils/ contains environment writing, status/presence, logging, security, and setup checks, which are the glue for safe startup and runtime health.
- The repo includes tests for nearly every subsystem, indicating the architecture is modular and designed around explicit boundaries rather than ad hoc scripting.
- Internationalization is cross-cutting across bot and web (locales/), but it is a presentation concern rather than a core data-flow layer.
12. End-to-end flow
- Typical flow: game server emits logs and save files → ingestion/parsing modules normalize them → database persists raw and derived state → trackers and schedulers compute actions → Discord and web UI present the results or issue commands back via RCON/Panel APIs.
- The architecture is therefore a closed loop around a central SQLite state store, with Discord and the web panel as two front ends over the same operational backend.
Main entry points: database.js SQLite DB · index.js Bot runtime · multi-server.js Multi-server · server.js Web server
Components 20
Runtimes
Primary processes and service boundaries.
- Bot runtime · Starts the Discord bot and shared modules.
src/index.js - Multi-server · Isolates per-server state, config, and runtime wiring.
src/server/multi-server.js - Console input · Optional stdin control surface for local administration.
src/stdin-console.js
Integrations
Connections to Discord, game servers, and hosted panel APIs.
- Slash commands · Player lookup, stats, server, RCON, panel, and thread actions.
src/commands - Bot modules · Embeds, chat relay, presence, alerts, status channels, and recurring automation.
src/modules - RCON core · Direct command execution and server info queries.
src/rcon/rcon.js - Panel API · Pterodactyl-side control boundary for hosted setups.
src/server/panel-api.js - Panel RCON · Panel-backed command channel for managed servers.
src/rcon/panel-rcon.js - Game agent · HumanitZ server-side bridge for data extraction and control.
src/game-server/humanitz-agent.js
Data Layer
Persistence, parsing, and derived game-state processing.
- Log watcher · Tails server logs and emits parsed events.
src/modules/log-watcher.js - Save service · Pulls and schedules world-state snapshots from save files.
src/parsers/save-service.js - Save parser · Decodes .sav world state into structured entities.
src/parsers/save-parser.js - SQLite DB · Central persistence for configs, events, snapshots, and metrics.
src/db/database.js - Diff engine · Compares consecutive snapshots and item state.
src/db/diff-engine.js - Trackers · Playtime, kills, player stats, and snapshot history.
src/tracking - Config layer · Validation, migration, and repository-backed configuration.
src/db/config-repository.js
Web Dashboard
Express app and browser UI for operations.
- Web server · Dashboard API and static asset server.
src/web-map/server.js - Web auth · Role-gated access for dashboard actions.
src/web-map/auth.js - Dashboard UI · Map, players, chat, database, admin, and settings screens.
src/web-map/public/app.js - Session store · Persistent web session storage for authenticated dashboard use.
src/web-map/session-stores/sqlite-store.js
Connections 26
- Bot runtime → Multi-server: starts · Boots the tenant-aware bot/runtime orchestration.
- Bot runtime → Slash commands: loads · Registers slash-command handlers.
- Bot runtime → Bot modules: loads · Initializes Discord automation modules.
- Bot runtime → SQLite DB: uses · Reads and writes shared state.
- Bot runtime → Config layer: loads · Resolves runtime configuration.
- Console input → Multi-server: controls · Provides local operator control.
- Slash commands → RCON core: executes · Issues direct server commands.
- Slash commands → Panel API: controls · Routes hosted-server actions through panel APIs.
- Bot modules → Log watcher: consumes · Turns log events into chat/activity outputs.
- Bot modules → SQLite DB: reads/writes · Stores and reads operational state.
- Log watcher → Save parser: normalizes · Feeds structured world-state parsing.
- Save service → Save parser: pulls · Schedules and loads save-file snapshots.
- Save parser → Diff engine: compares · Derives state changes between snapshots.
- Diff engine → SQLite DB: persists · Writes derived changes and history.
- Trackers → SQLite DB: reads/writes · Builds analytics from persisted events.
- Game agent → Save service: exposes · Acts as the server-side extraction bridge.
- Game agent → RCON core: invokes · Supports live command/control paths.
- Panel API → Panel RCON: backs · Provides managed-host command execution.
- Web server → Web auth: protects · Gates sensitive dashboard routes.
- Web server → Session store: stores · Persists authenticated sessions.
- Web server → SQLite DB: reads/writes · Serves the same operational state as the bot.
- Dashboard UI → Web server: calls · Consumes API endpoints and rendered assets.
- Multi-server → SQLite DB: partitions · Keeps per-server data isolated in shared persistence.
- Multi-server → RCON core: manages · Maintains per-server command connections.
- Multi-server → Save service: schedules · Coordinates per-server snapshot collection.
- Config layer → SQLite DB: stores · Keeps config in the database-backed settings model.