ShaiBot/docs/ARCHITECTURE.md

ShaiBot Architecture

This manual describes ShaiBot's implementation structure at a level useful to maintainers. For exact behavior, the current code remains authoritative.

Runtime

index.js initializes the Discord client and MongoDB connection, creates the interaction collections, initializes shared systems/indexes, loads handlers, and logs the bot in.

Interaction modules are discovered into collections such as:

client.commands
client.legacyCommands
client.aliases
client.buttons
client.selectMenus
client.modals

Before manually wiring a new component into the central router, check whether the filesystem loader already supports it.

Preferred Layering

ShaiBot favors:

Discord command / button / select menu
                ↓
          shared utility
                ↓
      Mongo / economy / profile

Discord wrappers should remain thin. Shared rules belong in utils/.

A feature reachable from multiple interfaces should normally have one authoritative implementation.

Important Shared Utilities

Examples include:

---

Utility Responsibility

---

cookieEconomy.js Cookie balances, transfers, cooldowns, economy primitives

crumbCollect.js Shared Cookie collection

crumbSlots.js Slots

crumbBlackjack.js Blackjack

crumbRoulette.js Roulette

cookieHeist.js Vault Heist

bankruptcy.js Bankruptcy/recovery

profileSystem.js Profiles, achievements, badges, activity

profileMaintenance.js Profile audit/reconciliation

interactionSession.js Shared single-owner interaction sessions

permissions.js Administrator/bot-author checks

pokerEngine.js Pure Hold'em engine

crumbPoker.js Persistent Poker service

pokerDiscord.js Poker Discord rendering/components

pokerProfile.js Poker progression bridge

crumbleStrike.js Cooperative encounter state/combat

MongoDB

Important collections include:

items_cookies
cooldown_cookies
items_games
items_special_games
stats_profiles
items_achievements
guild_badges
config_achievements

Indexes are part of correctness, not only performance.

ShaiBot intentionally avoids requiring multi-document MongoDB transactions. Depending on the subsystem it instead uses:

• Atomic filtered updates
• Unique indexes
• Optimistic version checks
• Idempotency markers
• Persistent resolution state
• Compensating writes

Concurrency

Assume users can double-click, spam controls, act simultaneously, race a timeout, or restart the bot during a transition.

Stateful systems should answer:

What is authoritative?
Can two interactions both succeed?
Can money move twice?
What happens if the process stops after the first write?
Can the operation safely be retried?

Do not rely on process-local flags for correctness that must survive a restart.

Discord Interactions

Button visibility is never authorization.

For potentially slow stateful interactions, acknowledge Discord early using the response style appropriate to that flow.

Do not globally defer every interaction from the central router because different modules legitimately use reply, update, deferReply, or deferUpdate.

Critical state should not exist only in an embed/footer.

Permissions

Administrative access is centralized through the shared permission utility.

Administrative access may include:

Discord Administrator
OR
BOT_AUTHOR_ID

Do not hard-code administrative Discord IDs.

Deployment

Typical production workflow:

node --check path/to/changed-file.js
pm2 restart ShaiBot
pm2 logs ShaiBot --lines 100

Syntax checking is useful, but economy and persistent-state changes still require behavioral testing.

Maintainer Checklist

Before shipping a stateful change:

• Identify the authoritative state.
• Check duplicate-click behavior.
• Check simultaneous-user behavior.
• Check insufficient-balance behavior.
• Check restart/recovery behavior.
• Check private/public information boundaries.
• Check whether profile tracking can safely fail without corrupting settlement.
• Inspect Mongo after a controlled live test.