# 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:

``` js
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:

``` text
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:

``` text
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:

``` text
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:

``` text
Discord Administrator
OR
BOT_AUTHOR_ID
```

Do not hard-code administrative Discord IDs.

## Deployment

Typical production workflow:

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