# qs-zuq/humanitzbot architecture

> Architecture diagram of the GitHub repository qs-zuq/humanitzbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qs-zuq/humanitzbot
- Repository: https://github.com/qs-zuq/humanitzbot

## Overview

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: [`src/db/database.js`](https://github.com/qs-zuq/humanitzbot/blob/main/src/db/database.js) (SQLite DB), [`src/index.js`](https://github.com/qs-zuq/humanitzbot/blob/main/src/index.js) (Bot runtime), [`src/server/multi-server.js`](https://github.com/qs-zuq/humanitzbot/blob/main/src/server/multi-server.js) (Multi-server), [`src/web-map/server.js`](https://github.com/qs-zuq/humanitzbot/blob/main/src/web-map/server.js) (Web server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtimes"]
  node_index["Bot runtime<br/>entrypoint<br/>[index.js]"]
  node_multi_server["Multi-server<br/>tenant manager<br/>[multi-server.js]"]
  node_stdin_console["Console input<br/>operator console<br/>[stdin-console.js]"]
end

subgraph group_integration["Integrations"]
  node_commands["Slash commands<br/>discord commands"]
  node_modules["Bot modules<br/>discord automation"]
  node_rcon["RCON core<br/>server control<br/>[rcon.js]"]
  node_panel_api["Panel API<br/>managed hosting<br/>[panel-api.js]"]
  node_panel_rcon["Panel RCON<br/>websocket rcon<br/>[panel-rcon.js]"]
  node_agent["Game agent<br/>server bridge<br/>[humanitz-agent.js]"]
end

subgraph group_data["Data Layer"]
  node_log_watcher["Log watcher<br/>ingestion<br/>[log-watcher.js]"]
  node_save_service["Save service<br/>snapshot ingestion<br/>[save-service.js]"]
  node_save_parser["Save parser<br/>binary parser<br/>[save-parser.js]"]
  node_db[("SQLite DB<br/>system of record<br/>[database.js]")]
  node_diff_engine["Diff engine<br/>change detection<br/>[diff-engine.js]"]
  node_trackers["Trackers<br/>derived analytics"]
  node_config["Config layer<br/>settings management"]
end

subgraph group_web["Web Dashboard"]
  node_web_server["Web server<br/>express api<br/>[server.js]"]
  node_auth["Web auth<br/>discord oauth<br/>[auth.js]"]
  node_frontend["Dashboard UI<br/>browser app<br/>[app.js]"]
  node_session_store["Session store<br/>sqlite sessions<br/>[sqlite-store.js]"]
end

node_index -->|"starts"| node_multi_server
node_index -->|"loads"| node_commands
node_index -->|"loads"| node_modules
node_index -->|"uses"| node_db
node_index -->|"loads"| node_config
node_stdin_console -->|"controls"| node_multi_server
node_commands -->|"executes"| node_rcon
node_commands -->|"controls"| node_panel_api
node_modules -->|"consumes"| node_log_watcher
node_modules -->|"reads/writes"| node_db
node_log_watcher -->|"normalizes"| node_save_parser
node_save_service -->|"pulls"| node_save_parser
node_save_parser -->|"compares"| node_diff_engine
node_diff_engine -->|"persists"| node_db
node_trackers -->|"reads/writes"| node_db
node_agent -->|"exposes"| node_save_service
node_agent -->|"invokes"| node_rcon
node_panel_api -->|"backs"| node_panel_rcon
node_web_server -->|"protects"| node_auth
node_web_server -->|"stores"| node_session_store
node_web_server -->|"reads/writes"| node_db
node_frontend -->|"calls"| node_web_server
node_multi_server -->|"partitions"| node_db
node_multi_server -->|"manages"| node_rcon
node_multi_server -->|"schedules"| node_save_service
node_config -->|"stores"| node_db

click node_index "https://github.com/qs-zuq/humanitzbot/blob/main/src/index.js"
click node_multi_server "https://github.com/qs-zuq/humanitzbot/blob/main/src/server/multi-server.js"
click node_stdin_console "https://github.com/qs-zuq/humanitzbot/blob/main/src/stdin-console.js"
click node_commands "https://github.com/qs-zuq/humanitzbot/tree/main/src/commands"
click node_modules "https://github.com/qs-zuq/humanitzbot/tree/main/src/modules"
click node_rcon "https://github.com/qs-zuq/humanitzbot/blob/main/src/rcon/rcon.js"
click node_panel_api "https://github.com/qs-zuq/humanitzbot/blob/main/src/server/panel-api.js"
click node_panel_rcon "https://github.com/qs-zuq/humanitzbot/blob/main/src/rcon/panel-rcon.js"
click node_agent "https://github.com/qs-zuq/humanitzbot/blob/main/src/game-server/humanitz-agent.js"
click node_log_watcher "https://github.com/qs-zuq/humanitzbot/blob/main/src/modules/log-watcher.js"
click node_save_service "https://github.com/qs-zuq/humanitzbot/blob/main/src/parsers/save-service.js"
click node_save_parser "https://github.com/qs-zuq/humanitzbot/blob/main/src/parsers/save-parser.js"
click node_db "https://github.com/qs-zuq/humanitzbot/blob/main/src/db/database.js"
click node_diff_engine "https://github.com/qs-zuq/humanitzbot/blob/main/src/db/diff-engine.js"
click node_trackers "https://github.com/qs-zuq/humanitzbot/tree/main/src/tracking"
click node_web_server "https://github.com/qs-zuq/humanitzbot/blob/main/src/web-map/server.js"
click node_auth "https://github.com/qs-zuq/humanitzbot/blob/main/src/web-map/auth.js"
click node_frontend "https://github.com/qs-zuq/humanitzbot/blob/main/src/web-map/public/app.js"
click node_session_store "https://github.com/qs-zuq/humanitzbot/blob/main/src/web-map/session-stores/sqlite-store.js"
click node_config "https://github.com/qs-zuq/humanitzbot/blob/main/src/db/config-repository.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_multi_server,node_stdin_console toneBlue
class node_commands,node_modules,node_rcon,node_panel_api,node_panel_rcon,node_agent toneAmber
class node_log_watcher,node_save_service,node_save_parser,node_db,node_diff_engine,node_trackers,node_config toneMint
class node_web_server,node_auth,node_frontend,node_session_store toneRose
```

## Components

### Runtimes

Primary processes and service boundaries.

- [Bot runtime](https://github.com/qs-zuq/humanitzbot/blob/main/src/index.js): entrypoint · Starts the Discord bot and shared modules. · `src/index.js`
- [Multi-server](https://github.com/qs-zuq/humanitzbot/blob/main/src/server/multi-server.js): tenant manager · Isolates per-server state, config, and runtime wiring. · `src/server/multi-server.js`
- [Console input](https://github.com/qs-zuq/humanitzbot/blob/main/src/stdin-console.js): operator console · Optional stdin control surface for local administration. · `src/stdin-console.js`

### Integrations

Connections to Discord, game servers, and hosted panel APIs.

- [Slash commands](https://github.com/qs-zuq/humanitzbot/tree/main/src/commands): discord commands · Player lookup, stats, server, RCON, panel, and thread actions. · `src/commands`
- [Bot modules](https://github.com/qs-zuq/humanitzbot/tree/main/src/modules): discord automation · Embeds, chat relay, presence, alerts, status channels, and recurring automation. · `src/modules`
- [RCON core](https://github.com/qs-zuq/humanitzbot/blob/main/src/rcon/rcon.js): server control · Direct command execution and server info queries. · `src/rcon/rcon.js`
- [Panel API](https://github.com/qs-zuq/humanitzbot/blob/main/src/server/panel-api.js): managed hosting · Pterodactyl-side control boundary for hosted setups. · `src/server/panel-api.js`
- [Panel RCON](https://github.com/qs-zuq/humanitzbot/blob/main/src/rcon/panel-rcon.js): websocket rcon · Panel-backed command channel for managed servers. · `src/rcon/panel-rcon.js`
- [Game agent](https://github.com/qs-zuq/humanitzbot/blob/main/src/game-server/humanitz-agent.js): server bridge · 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](https://github.com/qs-zuq/humanitzbot/blob/main/src/modules/log-watcher.js): ingestion · Tails server logs and emits parsed events. · `src/modules/log-watcher.js`
- [Save service](https://github.com/qs-zuq/humanitzbot/blob/main/src/parsers/save-service.js): snapshot ingestion · Pulls and schedules world-state snapshots from save files. · `src/parsers/save-service.js`
- [Save parser](https://github.com/qs-zuq/humanitzbot/blob/main/src/parsers/save-parser.js): binary parser · Decodes .sav world state into structured entities. · `src/parsers/save-parser.js`
- [SQLite DB](https://github.com/qs-zuq/humanitzbot/blob/main/src/db/database.js): system of record · Central persistence for configs, events, snapshots, and metrics. · `src/db/database.js`
- [Diff engine](https://github.com/qs-zuq/humanitzbot/blob/main/src/db/diff-engine.js): change detection · Compares consecutive snapshots and item state. · `src/db/diff-engine.js`
- [Trackers](https://github.com/qs-zuq/humanitzbot/tree/main/src/tracking): derived analytics · Playtime, kills, player stats, and snapshot history. · `src/tracking`
- [Config layer](https://github.com/qs-zuq/humanitzbot/blob/main/src/db/config-repository.js): settings management · Validation, migration, and repository-backed configuration. · `src/db/config-repository.js`

### Web Dashboard

Express app and browser UI for operations.

- [Web server](https://github.com/qs-zuq/humanitzbot/blob/main/src/web-map/server.js): express api · Dashboard API and static asset server. · `src/web-map/server.js`
- [Web auth](https://github.com/qs-zuq/humanitzbot/blob/main/src/web-map/auth.js): discord oauth · Role-gated access for dashboard actions. · `src/web-map/auth.js`
- [Dashboard UI](https://github.com/qs-zuq/humanitzbot/blob/main/src/web-map/public/app.js): browser app · Map, players, chat, database, admin, and settings screens. · `src/web-map/public/app.js`
- [Session store](https://github.com/qs-zuq/humanitzbot/blob/main/src/web-map/session-stores/sqlite-store.js): sqlite sessions · Persistent web session storage for authenticated dashboard use. · `src/web-map/session-stores/sqlite-store.js`

## Connections

- 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.
