Technical Breakdown

Relaxy! is a multipurpose Discord bot I first wrote in early 2019 and have rewritten more times than I would like to admit. It is a plain Node.js program in modern JavaScript (ES6 modules), typed with JSDoc and .d.ts files rather than TypeScript syntax, so there is no build step at all: the bot runs directly from source, and reloads most of itself while it is still running. It runs as one supervisor process plus a few worker processes, and it hs the possibility of scaling across machines easily if needed.

A guild lives on exactly one cluster. Only that cluster may act on it, so anything fleet-wide has to be broadcast, and anything that must happen exactly once needs a designated cluster to happen on.

./start
  │
  ├─ bot/Manager.js  ──► src/Manager/Manager.js        ONE per host
  │     owns the console, SelfRepair, the dashboard API, host reporting
  │     has NO gateway connection and NO Mongoose connection of its own
  │
  └─ forks N × bot/Client.js ──► src/Client/Relaxy.js  ONE per cluster
        owns guilds, commands, events, the database cache, the music player

• _main execs bwrap. System paths come in read-only, the bot's own directory is the single writable mount, /tmp is a throwaway tmpfs, and the PID, IPC and UTS namespaces are unshared. $HOME is deliberately not bound, so the cache directory is pointed at the sandbox's own tmpfs instead.
• ./start sources nvm if Node is not already on PATH, exports UV_THREADPOOL_SIZE=64 for libuv's fs and crypto work, and execs Node under nice -n -20 with the highest scheduling priority along with --stack_size=1000, --trace-uncaught and --max-old-space-size=6144. It also picks the entry point. The manager normally, a single client under --client, the cross-hosting bridge under --bridge.
• The manager creates every directory the fleet writes to, then does two things before a single cluster is forked. It overlays the operator-mutable settings (version, owners, status lines) from MongoDB onto the .env seeds. Then it warms the CDN text cache, so a shard that boots into a CDN outage still finds its word lists on disk.
• Clusters are rolled out ~7s apart. Each one loads its modules in parallel, starts loading commands and connecting to Mongo at the same time (command loading is file-only and does not need the database), then logs into the gateway. Music extractors load afterwards, deliberately off the critical path, so commands work before the music engine is finished.
• Only once every shard it owns is actually properly connected does a cluster report ready. Readiness is counted off each cluster's own clientReady event.
• Once the last cluster lands, the feature intervals start: mutes, reminders, ticket systems, forums, clearing channels. A stalled startup is caught by a watchdog whose budget scales with the fleet (clusters × 7s + 60s, floor of 5 minutes); past that it keeps naming the clusters that are still not ready, every 60s, until they recover automatically or I step in.

What a write actually does

client.save(guildId, { alter: 'ch.t.cl', value: entries })
  └─ load()     make sure the document is cached
  └─ queue()    mutate the cached object SYNCHRONOUSLY, mark it dirty
       └─ 200 ms debounce, per document
            └─ flush -> strip defaults -> mongoose.updateOne

• The actual Mongo I/O is offloaded to a worker thread, so nothing on the command path ever waits on the database.
• A read immediately after a write sees the new value on this cluster, because the queue mutates the cached object before the flush ever happens.
• Caches never expire, but they do have a ceiling. A sweep every minute drops the oldest entries past a per-cache limit, and drops much harder when the process is near its memory budget. Anything with a write still pending is never evicted. Evicting a dirty document makes the change silently revert minutes later, which is a big headache waiting to happen.
• Repeated strings: moderator ids, mute reasons, role ids are interned once per guild and referenced by integer index. The registry is append-only by construction and unwritable from outside, because setting it wholesale would detach every warning and mute in the guild at once. (BAD)

export default {
    name:        'commandname',           // The key it is stored under.
    aliases:     ['alias'],
    usage:       '=commandname <args>',
    description: 'Long help text. Markdown, multi-line.',

    slashDescription: 'One line, 100 chars max.',
    slash:            new Discord.SlashCommandBuilder()
                          .addStringOption(o => o.setName('target')...),

    args:     true,      // refuse with the usage line when given no arguments
    defer:    true,      // make discord wait longer before marking interaction as invalid
    cooldown: 20,        // seconds, per user
    owner:    false,
    leaveout: false,     // exclude from registration

    permissionsUser: ['SEND_MESSAGES', 'MANAGE_MESSAGES' and so on],
    permissionsBot:  ['SEND_MESSAGES', 'EMBED_LINKS' and so on],
    There's also suggestedPermissionsUser and suggestedPermissionsBot for more complicated commands

    async run(client, message, args, guild, interaction) { … }
};

Three ways to run a command

• Slash arguments arrive per option. /appealchannel target:"thread Moderators" is one argument where the prefix path gives two, so anything that reads its line word by word has to normalize first.
• Components route by the customId prefix, straight back into the command of that name. They are not re-checked against permissionsUser on the way in. That is right for a component that only affects whoever pressed it and wrong for one that reads moderation data, which has to check the presser itself.
• Discord caps a slash description at 100 characters. So a long description on a complicated command usually made registration fail, so I created slashDescription which always fits parameters and is checked for correctness upon being loaded in.
• Three seconds. Discord kills an interaction that has not been acknowledged in that time, so anything doing several reads, a member fetch, a broadcast or an image render sets defer. A deferred command must never call interaction.reply() afterwards, it kinda just breaks the interaction flow.

relaxy-private/
├── _main                     # bwrap sandbox, then execs ./start inside it
├── start                     # launcher: ./start [--client|--bridge], Node flags
├── detect_os.js              # host detection (distro and hardware, separately)
├── package.json              # ESM, 47 dependencies, no build step
├── tsconfig.json             # checkJs only, nothing is ever compiled
├── bot/                      # entry points, commands, events
│   ├── Manager.js            # supervisor process entry
│   ├── Client.js             # cluster/client process entry
│   ├── Bridge.js             # cross-hosting bridge entry (one per machine)
│   ├── commands/             # 186 modules in 6 categories
│   │   ├── administrator/  fun/  image/
│   │   └── miscellaneous/  moderation/  music/
│   └── events/               # discord/ (47) + music/ (11)
├── src/                      # the engine
│   ├── Core/                 # ModuleLoader, HotPatch, DataTable (the IPC enum)
│   ├── Config/               # Env, Config, Settings (.env + the database overlay)
│   ├── Assets/               # CDN.js (every asset path and URL) and Storage.js
│   ├── Bridge/               # MainFrame, for cross-hosting
│   ├── Utils/                # CookieUtils, NetworkErrors, RestRetry
│   ├── Manager/
│   │   ├── Manager.js
│   │   ├── Core/             # SelfRepair, HeartBeatManager, LogWorker
│   │   └── Modules/          # ClusterSpawn, ConsoleInput, DashboardApi
│   └── Client/
│       ├── Relaxy.js         # the bot client
│       └── Modules/
│           ├── Core/         # CommonRoutines, Utilities, Statistics, LoadMonitor
│           ├── Database/     # SchemaEngine, GarbageCollector, Blueprints/
│           ├── Moderation/   # Moderation, ScamOcr, CensorExceptions
│           ├── Guilds/       # GuildLink (cross-server), Creators, Panels, Tickets
│           ├── Progression/  # levels, rewards, voice + reaction activity
│           ├── MusicPlayer/  # the vendored player, equalizer, extractors
│           ├── Workers/      # DatabaseWorker, FileWorker (worker threads)
│           ├── Handlers/  Cards/  Dashboard/  VoiceRecorder/
│           └── ADSR/         # active diagnosis + the cross-process rate limiter
├── types/                    # .d.ts declarations
├── docs/                     # 14 design documents
├── scripts/                  # music/ upgrade pipeline, maintenance/ checks
├── logs/                     # per-cluster log output
└── storage/                  # runtime caches (users, guilds, cdn-cache)

The launcher wraps the whole program in a bubblewrap sandbox before anything else happens. System directories come in read-only, the bot's own directory is the single writable mount, /tmp is a throwaway tmpfs, and the PID, IPC and UTS namespaces are unshared. Then it execs the real launcher from the inside.

Every read in the host detection is best-effort. Under bwrap parts of /proc and /sys may not be mounted at all, and a sandboxed host has to degrade gracefully to "plain Linux" rather than throw at import time and take the whole process down with it. That one caused some headaches.