added more documentation

docs/ARCHITECTURE.md

@@ -0,0 +1,185 @@
+# 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.