DeSqBlocki
186 lines
4.7 KiB
Markdown
186 lines
4.7 KiB
Markdown
# 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.
|