# princeofcookies/masterbot architecture

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

- Interactive diagram: https://gitdiagram.com/princeofcookies/masterbot
- Repository: https://github.com/princeofcookies/masterbot

## Overview

MasterBot hosts multiple configurable Discord bots, either together or as individual PM2 workers. Its main workflow discovers each bot and its environment, creates a client and optional SQL pool, loads shared or bot-specific tools, functions, commands, and events, then logs in. A separate operations branch monitors PM2 health and resource guardrails, alerts, and supports Discord-based control. The README also documents an optional Rust watchdog. Edges are limited to calls shown in excerpts or relationships documented in the README; unsampled internals are not assumed.

Main entry points: [`src/core/botLoader.js`](https://github.com/princeofcookies/masterbot/blob/master/src/core/botLoader.js) (Bot startup), [`src/pm2/healthMonitor.js`](https://github.com/princeofcookies/masterbot/blob/master/src/pm2/healthMonitor.js) (Health monitor), [`src/control/pm2Control.js`](https://github.com/princeofcookies/masterbot/blob/master/src/control/pm2Control.js) (Bot controls), [`src/pm2/pm2Cache.js`](https://github.com/princeofcookies/masterbot/blob/master/src/pm2/pm2Cache.js) (PM2 status cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_entry["Host entrypoint<br/>[index.js]"]
  node_worker["Bot worker<br/>[botWorker.js]"]
  node_discovery["Bot discovery<br/>[botDiscovery.js]"]
  node_loader["Bot startup<br/>[botLoader.js]"]
  node_client["Client factory<br/>[clientfactory.js]"]
  node_defaults["Client defaults<br/>[defaults.js]"]
  node_database["SQL pool<br/>[database.js]"]
end

subgraph group_loading["Loading and events"]
  node_functions["Function loader<br/>[functionloader.js]"]
  node_events["Event loader<br/>[eventloader.js]"]
  node_filecache["File discovery cache"]
  node_commands["Command handler<br/>[handleCommands.js]"]
  node_hashcache[("Command hash cache")]
end

subgraph group_operations["PM2 operations"]
  node_control["Discord control app<br/>[controlBot.js]"]
  node_pm2control["Bot controls<br/>[pm2Control.js]"]
  node_alerts["User alerts<br/>[alertUsers.js]"]
  node_health["Health monitor<br/>[healthMonitor.js]"]
  node_pm2client["PM2 client<br/>[pm2Client.js]"]
  node_pm2cache[("PM2 status cache<br/>[pm2Cache.js]")]
  node_alertsink["Alert sink<br/>[alertSink.js]"]
  node_formatter["Status formatter<br/>[statusFormatter.js]"]
  node_allocator["Resource allocator"]
  node_ecosystem["PM2 app config"]
end

subgraph group_watchdog["Optional watchdog"]
  node_watchdog["Rust watchdog<br/>[main.rs]"]
end

node_operator(("Operator / bot user"))
node_discord{{"Discord API"}}
node_mysql[("MySQL")]
node_pm2{{"PM2"}}

node_operator -.->|"uses"| node_discord
node_entry -->|"starts bots"| node_loader
node_entry -->|"starts monitor"| node_health
node_worker -->|"starts one bot"| node_loader
node_loader -->|"finds bots"| node_discovery
node_loader -->|"creates client"| node_client
node_client -->|"uses defaults"| node_defaults
node_loader -->|"creates pool"| node_database
node_database -->|"queries"| node_mysql
node_loader -->|"loads functions"| node_functions
node_loader -->|"loads events"| node_events
node_functions -->|"discovers files"| node_filecache
node_events -->|"discovers files"| node_filecache
node_commands -->|"discovers commands"| node_filecache
node_commands -->|"checks hashes"| node_hashcache
node_loader -.->|"logs in"| node_discord
node_control -->|"handles actions"| node_pm2control
node_control -->|"uses alerts"| node_alerts
node_control -.->|"registers commands"| node_discord
node_pm2control -->|"validates bots"| node_discovery
node_pm2control -->|"reads status"| node_pm2cache
node_pm2control -->|"runs commands"| node_pm2
node_health -->|"finds bots"| node_discovery
node_health -->|"reads status"| node_pm2cache
node_health -->|"requests actions"| node_pm2client
node_health -->|"sends alerts"| node_alertsink
node_health -->|"formats status"| node_formatter
node_health -->|"calculates allocations"| node_allocator
node_pm2client -->|"reads cached status"| node_pm2cache
node_pm2client -->|"validates bots"| node_discovery
node_pm2cache -->|"refreshes status"| node_pm2
node_ecosystem -.->|"configures apps"| node_pm2
node_watchdog -.->|"reads status"| node_pm2
node_watchdog -.->|"reports allocations"| node_operator

click node_entry "https://github.com/princeofcookies/masterbot/blob/master/index.js"
click node_worker "https://github.com/princeofcookies/masterbot/blob/master/src/worker/botWorker.js"
click node_discovery "https://github.com/princeofcookies/masterbot/blob/master/src/core/botDiscovery.js"
click node_loader "https://github.com/princeofcookies/masterbot/blob/master/src/core/botLoader.js"
click node_client "https://github.com/princeofcookies/masterbot/blob/master/src/core/clientfactory.js"
click node_defaults "https://github.com/princeofcookies/masterbot/blob/master/src/config/defaults.js"
click node_database "https://github.com/princeofcookies/masterbot/blob/master/src/core/database.js"
click node_functions "https://github.com/princeofcookies/masterbot/blob/master/src/core/functionloader.js"
click node_events "https://github.com/princeofcookies/masterbot/blob/master/src/core/eventloader.js"
click node_filecache "https://github.com/princeofcookies/masterbot/blob/master/src/cache/fileDiscoveryCache.js"
click node_commands "https://github.com/princeofcookies/masterbot/blob/master/src/functions/handlers/handleCommands.js"
click node_hashcache "https://github.com/princeofcookies/masterbot/blob/master/src/cache/commandHashCache.js"
click node_control "https://github.com/princeofcookies/masterbot/blob/master/src/control/controlBot.js"
click node_pm2control "https://github.com/princeofcookies/masterbot/blob/master/src/control/pm2Control.js"
click node_alerts "https://github.com/princeofcookies/masterbot/blob/master/src/control/alertUsers.js"
click node_health "https://github.com/princeofcookies/masterbot/blob/master/src/pm2/healthMonitor.js"
click node_pm2client "https://github.com/princeofcookies/masterbot/blob/master/src/pm2/pm2Client.js"
click node_pm2cache "https://github.com/princeofcookies/masterbot/blob/master/src/pm2/pm2Cache.js"
click node_alertsink "https://github.com/princeofcookies/masterbot/blob/master/src/pm2/alertSink.js"
click node_formatter "https://github.com/princeofcookies/masterbot/blob/master/src/pm2/statusFormatter.js"
click node_allocator "https://github.com/princeofcookies/masterbot/blob/master/src/pm2/resourceAllocator.js"
click node_ecosystem "https://github.com/princeofcookies/masterbot/blob/master/ecosystem.config.js"
click node_watchdog "https://github.com/princeofcookies/masterbot/blob/master/rust/masterbot-watchdog/src/main.rs"

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_entry,node_worker,node_discovery,node_loader,node_client,node_defaults,node_database,node_operator toneBlue
class node_functions,node_events,node_filecache,node_commands,node_hashcache,node_mysql toneAmber
class node_control,node_pm2control,node_alerts,node_health,node_pm2client,node_pm2cache,node_alertsink,node_formatter,node_allocator,node_ecosystem,node_discord toneMint
class node_watchdog toneRose
class node_pm2 toneIndigo
```

## Components

### Bot runtime

- [Host entrypoint](https://github.com/princeofcookies/masterbot/blob/master/index.js): `index.js`
- [Bot worker](https://github.com/princeofcookies/masterbot/blob/master/src/worker/botWorker.js): `src/worker/botWorker.js`
- [Bot discovery](https://github.com/princeofcookies/masterbot/blob/master/src/core/botDiscovery.js): `src/core/botDiscovery.js`
- [Bot startup](https://github.com/princeofcookies/masterbot/blob/master/src/core/botLoader.js): `src/core/botLoader.js`
- [Client factory](https://github.com/princeofcookies/masterbot/blob/master/src/core/clientfactory.js): `src/core/clientfactory.js`
- [Client defaults](https://github.com/princeofcookies/masterbot/blob/master/src/config/defaults.js): `src/config/defaults.js`
- [SQL pool](https://github.com/princeofcookies/masterbot/blob/master/src/core/database.js): `src/core/database.js`

### Loading and events

- [Function loader](https://github.com/princeofcookies/masterbot/blob/master/src/core/functionloader.js): `src/core/functionloader.js`
- [Event loader](https://github.com/princeofcookies/masterbot/blob/master/src/core/eventloader.js): `src/core/eventloader.js`
- [File discovery cache](https://github.com/princeofcookies/masterbot/blob/master/src/cache/fileDiscoveryCache.js): `src/cache/fileDiscoveryCache.js`
- [Command handler](https://github.com/princeofcookies/masterbot/blob/master/src/functions/handlers/handleCommands.js): `src/functions/handlers/handleCommands.js`
- [Command hash cache](https://github.com/princeofcookies/masterbot/blob/master/src/cache/commandHashCache.js): `src/cache/commandHashCache.js`

### PM2 operations

- [Discord control app](https://github.com/princeofcookies/masterbot/blob/master/src/control/controlBot.js): `src/control/controlBot.js`
- [Bot controls](https://github.com/princeofcookies/masterbot/blob/master/src/control/pm2Control.js): `src/control/pm2Control.js`
- [User alerts](https://github.com/princeofcookies/masterbot/blob/master/src/control/alertUsers.js): `src/control/alertUsers.js`
- [Health monitor](https://github.com/princeofcookies/masterbot/blob/master/src/pm2/healthMonitor.js): `src/pm2/healthMonitor.js`
- [PM2 client](https://github.com/princeofcookies/masterbot/blob/master/src/pm2/pm2Client.js): `src/pm2/pm2Client.js`
- [PM2 status cache](https://github.com/princeofcookies/masterbot/blob/master/src/pm2/pm2Cache.js): `src/pm2/pm2Cache.js`
- [Alert sink](https://github.com/princeofcookies/masterbot/blob/master/src/pm2/alertSink.js): `src/pm2/alertSink.js`
- [Status formatter](https://github.com/princeofcookies/masterbot/blob/master/src/pm2/statusFormatter.js): `src/pm2/statusFormatter.js`
- [Resource allocator](https://github.com/princeofcookies/masterbot/blob/master/src/pm2/resourceAllocator.js): `src/pm2/resourceAllocator.js`
- [PM2 app config](https://github.com/princeofcookies/masterbot/blob/master/ecosystem.config.js): `ecosystem.config.js`

### Optional watchdog

- [Rust watchdog](https://github.com/princeofcookies/masterbot/blob/master/rust/masterbot-watchdog/src/main.rs): `rust/masterbot-watchdog/src/main.rs`

### Other components

- **Operator / bot user**
- **Discord API**
- **MySQL**
- **PM2**

## Connections

- Operator / bot user → Discord API: uses (evidence: `README.md`)
- Host entrypoint → Bot startup: starts bots (evidence: `index.js`)
- Host entrypoint → Health monitor: starts monitor (evidence: `index.js`)
- Bot worker → Bot startup: starts one bot (evidence: `src/worker/botWorker.js`)
- Bot startup → Bot discovery: finds bots (evidence: `src/core/botLoader.js`)
- Bot startup → Client factory: creates client (evidence: `src/core/botLoader.js`)
- Client factory → Client defaults: uses defaults (evidence: `src/core/clientfactory.js`)
- Bot startup → SQL pool: creates pool (evidence: `src/core/botLoader.js`)
- SQL pool → MySQL: queries (evidence: `src/core/database.js`)
- Bot startup → Function loader: loads functions (evidence: `src/core/botLoader.js`)
- Bot startup → Event loader: loads events (evidence: `src/core/botLoader.js`)
- Function loader → File discovery cache: discovers files (evidence: `src/core/functionloader.js`)
- Event loader → File discovery cache: discovers files (evidence: `src/core/eventloader.js`)
- Command handler → File discovery cache: discovers commands (evidence: `src/functions/handlers/handleCommands.js`)
- Command handler → Command hash cache: checks hashes (evidence: `src/functions/handlers/handleCommands.js`)
- Bot startup → Discord API: logs in (evidence: `README.md`)
- Discord control app → Bot controls: handles actions (evidence: `src/control/controlBot.js`)
- Discord control app → User alerts: uses alerts (evidence: `src/control/alertUsers.js`)
- Discord control app → Discord API: registers commands (evidence: `README.md`)
- Bot controls → Bot discovery: validates bots (evidence: `src/control/pm2Control.js`)
- Bot controls → PM2 status cache: reads status (evidence: `src/control/pm2Control.js`)
- Bot controls → PM2: runs commands (evidence: `src/control/pm2Control.js`)
- Health monitor → Bot discovery: finds bots (evidence: `src/pm2/healthMonitor.js`)
- Health monitor → PM2 status cache: reads status (evidence: `src/pm2/healthMonitor.js`)
- Health monitor → PM2 client: requests actions (evidence: `src/pm2/healthMonitor.js`)
- Health monitor → Alert sink: sends alerts (evidence: `src/pm2/healthMonitor.js`)
- Health monitor → Status formatter: formats status (evidence: `src/pm2/healthMonitor.js`)
- Health monitor → Resource allocator: calculates allocations (evidence: `src/pm2/healthMonitor.js`)
- PM2 client → PM2 status cache: reads cached status (evidence: `src/pm2/pm2Client.js`)
- PM2 client → Bot discovery: validates bots (evidence: `src/pm2/pm2Client.js`)
- PM2 status cache → PM2: refreshes status (evidence: `src/pm2/pm2Cache.js`)
- PM2 app config → PM2: configures apps (evidence: `README.md`)
- Rust watchdog → PM2: reads status (evidence: `README.md`)
- Rust watchdog → Operator / bot user: reports allocations (evidence: `README.md`)