Gambling BOT – Discord Casino & Admin Dashboard Ecosystem

• Per-guild virtual currency with immutable transaction logs and admin-approved deposits/withdrawals (suited to RP servers).
• Configurable casino games with computed RTP, not magic numbers.
• Engagement systems: daily bonuses, VIP rooms, predictions, and recurring raffles.
• A web dashboard for managers and server admins to inspect users, cash flow, and settings.
• One shared TypeScript package so bot and dashboard never disagree on schemas or math.

Each application deploys independently but stays aligned through gambling-bot-shared and a single MongoDB database. The Discord bot owns gameplay, workers, and Discord API side effects; the dashboard owns OAuth, forms, and read-heavy analytics.

• Models: User, Transaction, GuildConfiguration, Prediction, VipRoom, BlackjackGame, AtmRequest, Raffle, and related indexes.
• defaultCasinoSettings and readableGameNames for UI labels.
• Zod: casinoSettingsSchema, channelsFormSchema, bonusFormSchema, vipSettingsFormSchema, managerRoleFormSchema.
• Utilities: calculateRTP (per game), calculateBonusReward, generateBonusPreview, validateBetAmount, validatePredictionBet.
• Constants: roulette layout (MINI_NUMBERS), lottery draw sizes, transaction type/source enums.

• balance - withdrawable cash (ATM withdrawals only touch this).
• bonusBalance - non-withdrawable funds from daily bonuses and admin grants; spent first on casino bets.
• lockedBalance - funds reserved while a bet is open; released on settle or refund.
• Transaction - append-only log: types deposit, withdraw, bet, win, refund, bonus, vip; sources command, manual, web, system, casino; optional betId for correlated rounds.

Casino bets use reserveCasinoBet /settleCasinoWinnings inside MongoDB multi-document transactions: duplicate betId is rejected, bonus balance is consumed before cash, and locked balance tracks exposure until settlement.

1. Check registration, allowed casino channels, and per-game cooldowns.
2. Validate bet against min/max and available cash + bonus.
3. reserveCasinoBet with a generated betId.
4. Run game logic (RNG, buttons, multi-step embeds).
5. settleCasinoWinnings and render result embeds.

calculateRTP in the shared package derives effective return from guild settings and game-specific probability-not hardcoded labels. The dashboard shows live RTP (with warnings when RTP ≤ 90% or ≥ 100%) while editing casino settings.

• Dice: (1/6) × winMultiplier.
• Coinflip: 0.5 × winMultiplier.
• Slots: Σ P(3-of-a-kind per symbol) × multiplier.
• Lottery: hypergeometric match probabilities × tier multipliers.
• Roulette: separate RTP per bet type from wheel layout.
• Plinko: binomial path probabilities × bin multipliers.
• RPS: 1 − casinoCut; Golden Jackpot: winMultiplier / oneInChance.
• Blackjack: documented ~99.4% baseline; prediction/raffle RTP not auto-calculated.

for (let k = 0; k <= N; k++) {
  const p = C(N,k) * 0.5^k * 0.5^(N-k)
  rtp += p * binMultipliers[k]
}
return rtp * 100

bonusSettings per guild controls linear or exponential streak growth, caps, reset-on-max, and weekly / monthly milestone bonuses. Rewards credit bonusBalance only-keeping farmed value inside the casino economy.

• /bonus check - 28-day preview calendar (shared generateBonusPreview).
• /bonus claim - 24h cooldown enforced in DB; streak + transaction logged.
• Dashboard: bonus form + live calendar preview when editing settings.
• Admin can grant or revoke bonus balance from the users table.

Players buy private channels for a duration (days/weeks). Config covers category, owner/member roles, pricing per day, creation fee, and multi-member support (maxMembers, pricePerAdditionalMember).

• Dedicated prediction action/log channels in guild config.
• predictionAutolock worker (1 min) and predictionCleanup worker (daily).
• validatePredictionBet shared between bot and tests.
• Win payout: stake × odds; cancellations issue refund transactions.

• /raffle create, cancel, and ticket purchase flows with atomic DB updates.
• raffleDraw worker checks every minute for due draws.
• Weighted random winner by ticket count; single-participant edge case refunds.
• Recurring raffles reschedule after each draw.
• Separate raffle action/log channels-configured in dashboard channel settings.

After Discord OAuth, users pick a guild where they are Administrator or hold the configured manager role. Routes live under /dashboard/g/[guildId]/[section] with permission gates (bot present, role check, Discord API rate-limit handling).

Long-running Discord bots cannot rely on players to finish every session. A shared runWorkerLoop scheduler starts on clientReady and runs idempotent jobs on intervals.

• VIP expiration - 1 min: revoke write access, sync permissions.
• Prediction autolock - 1 min: close betting at configured time.
• Raffle auto-draw - 1 min: pick winner, pay pot, reschedule repeats.
• Guild settings sync - 6 h: refresh cached config from MongoDB.
• Blackjack auto-stand - 1 h (delayed start): resolve abandoned hands.
• Prediction cleanup - daily: archive or remove stale documents.

The Discord bot repo treats correctness as part of the product: Vitest with separate unit and integration targets, ESLint + Prettier + tsc --noEmit in CI-style pnpm check.

• Unit: blackjack engine, roulette math, plinko path/render, RTP helpers, bet validation, cooldowns.
• Integration: casinoBet sessions, daily bonus claims, prediction bets, raffle DB, VIP DB, workers (autolock, raffle draw, blackjack autostand).
• mongodb-memory-server for hermetic database tests.
• Moderator simulate-* commands for dice, slots, lottery, golden jackpot, and transaction stress tests.

• Concurrency - MongoDB transactions + unique betId indexes prevent double-spend and duplicate settlement when users spam interactions.
• Dual balance - bonus-first bet consumption and locked balance keep withdrawable cash honest while still rewarding streak play.
• Interaction latency - multi-step games (blackjack, plinko animations) need clear error handling and workers for abandoned state.
• Config drift - central package + Zod schemas + guild sync worker keep bot memory and dashboard writes aligned.
• Permission model - dashboard distinguishes Discord Administrator vs configured manager role; settings UI hidden from managers who only need transactions/users.
• RP safety - gated ATM and manual transaction source document every balance change for moderator review.