A production-grade, modular Discord bot (~5,800 LOC) powering a 100+ member community server. Features a virtual economy, tiered moderation engine, multi-step verification workflows, ticket routing, application pipelines, and a fully interactive UI—all built with an async, event-driven architecture on discord.py.
| Area | What it demonstrates |
|---|---|
| Async Architecture | Fully asynchronous Python with asyncio, event-driven listeners, and dynamic cog loading with fallback introspection |
| Virtual Economy | Currency system with daily rewards, tiered word-count payouts, 6-category shop with rarity tiers, and an approval-gated purchase pipeline |
| Third-Party API Integration | Tupperbox webhook-to-user attribution engine—correlates proxied messages to real users within a sliding time window |
| Modular Plugin System | 14 independently loadable cogs with hot-reload support, organized by domain (moderation, economy, verification, etc.) |
| Rich Discord UI | Modals, persistent button panels, paginated views, dynamic dropdowns, and confirmation dialogs—all surviving bot restarts |
| Weighted Moderation | Three-tier warning system with 30-day time-decay, automatic escalation (kick/ban), and per-warning unique IDs |
| Anti-Abuse | Sliding-window spam detection, raid velocity alerts, per-user cooldowns, and configurable content filters |
| Data Persistence | Centralized JSON data layer across 11 stores with graceful error recovery and atomic read/write operations |
- Language: Python 3.10+
- Framework: discord.py 2.3+ (slash commands, modals, views, app commands)
- Async Runtime: asyncio
- HTTP Client: aiohttp (API integrations)
- Config Management: python-dotenv, JSON-based config
- Data Storage: File-based JSON persistence (11 data stores)
main.py # Entry point — bot init, dynamic cog loader
├── cogs/ # 14 feature modules (one per domain)
│ ├── core.py # Global error handler, help system
│ ├── shop.py # Economy engine, Tupperbox integration
│ ├── moderation.py # Warning system, kick/ban, staff notes
│ ├── automod.py # Spam detection, raid alerts, filters
│ ├── tickets.py # Multi-type ticket routing & archival
│ ├── applications.py # 4-type application pipeline
│ ├── verification.py # Passphrase-based rules verification
│ ├── age_verification.py # Multi-step ID verification workflow
│ ├── roles.py # 6-category self-serve role panels
│ ├── embed_creator.py # Staff embed builder (4 modes)
│ ├── welcome_goodbye.py # Join/leave event handling
│ ├── logging_cog.py # Audit logging to dedicated channels
│ ├── rules.py # Themed rules display system
│ └── server_info.py # Server info panel
├── utils/ # Shared utilities
│ ├── db.py # JSON read/write with error recovery
│ ├── checks.py # Permission predicates (staff, mod, admin)
│ ├── embeds.py # Embed factory functions
│ ├── views.py # Reusable UI: pagination, confirms, dropdowns
│ └── constants.py # Colors, config constants
├── config/
│ ├── config.json # Server IDs, channel mappings, categories
│ └── secrets.env # Bot token (excluded from VCS)
└── data/ # 11 JSON data stores + log archives
- Tiered word-count rewards via Tupperbox webhook correlation (200+ / 500+ / 800+ words)
- Daily randomized currency drops (15–30 Echoes)
- 6-category shop with rarity tiers (Common → Legendary), limited stock, and approval-gated purchases
- Player inventory tracking with purchase history
- Per-user, per-channel anti-farming cooldowns
- Weighted warnings — Minor (1pt), Major (3pt), Critical (5pt → instant ban)
- Time-decay — Each warning auto-expires 30 days after issuance; active totals recalculated live
- Auto-escalation — Automatic kick at 5 active points
- Staff notes — Non-punitive, permanent records alongside warning history
- Full audit trail — All actions logged with timestamps, staff attribution, and user DM notifications
- Sliding-window spam detection with escalating responses (warn → timeout)
- Join-velocity raid detection (configurable threshold, instant staff alerts)
- Content filtering with a persistent, editable word list
- 5 ticket types with category-based routing and per-user limits
- Archival workflow (close → archive category, not deletion)
- 4 application types (Student, Faculty, Ability, Item) with private review channels
- Staff approve/deny/request-changes pipeline with status tracking
- Rules verification — Split passphrase system; case/punctuation insensitive matching
- Age verification — Multi-step modal flow: DOB → confirmation → optional ID upload → staff review
- Persistent button panels that survive bot restarts (
timeout=None) - Paginated views with wrapping navigation
- Confirmation dialogs, dynamic dropdowns, and user-gated delete buttons
- 4-mode embed builder for staff (modal, advanced, quick, announcement)
Six role categories with exclusive/multi-select logic: Colors · Pronouns · Pings · Timezones · DM Status · Friend Requests
| Pattern | Application |
|---|---|
| Plugin / Cog | 14 modules loaded dynamically at startup with fallback introspection |
| Factory | Standardized embed builders (create_embed, create_log_embed, etc.) |
| Strategy | Injectable permission predicates (is_staff, is_moderator, is_admin) |
| Observer | Event listeners across cogs for message, member, and role events |
| Registry | Data-driven emoji → role mappings for 6 reaction-role categories |
| Data-Driven Config | Behavior defined in dictionaries (APP_TYPES, TicketType, SHOP_CATEGORIES), not code branches |
- Python 3.10+
- A Discord bot token with Server Members and Message Content intents enabled
# Clone the repository
git clone https://github.com/your-username/whispers-in-the-dark-bot.git
cd whispers-in-the-dark-bot
# Install dependencies
pip install -r requirements.txt
# Configure the bot
# 1. Edit config/config.json with your server/channel/role IDs
# 2. Add your bot token to config/secrets.env:
# BOT_TOKEN=your_token_here
# Run
python main.pyAll server-specific IDs (guild, channels, roles, categories) are defined in config/config.json. The bot token is stored in config/secrets.env and loaded via python-dotenv. No secrets are hard-coded.
Required Bot Permissions
Manage Roles · Manage Channels · Kick Members · Ban Members · View Channels · Send Messages · Manage Messages · Embed Links · Attach Files · Read Message History · Add Reactions
40+ slash commands across 8 domains
| Domain | Commands |
|---|---|
| Economy | /echoes, /daily, /shop, /shop-buy, /inventory, /echoes-manage, /echoes-check, /shop-add, /shop-remove, /shop-stock, /shop-approve, /shop-decline |
| Moderation | /warn, /warnings, /clearwarnings, /note, /kick, /ban, /unban |
| Verification | /set-code-phrase, /verification-panel, /age-verification-panel, /submit-id |
| Tickets | /ticket close|add|remove|reopen, /ticket_panel |
| Applications | /apply, /application_panel |
| Roles | /role-panel |
| Embeds | /create-embed, /advanced-embed, /quick-embed, /announcement-embed |
| Utility | /ping, /help, /rules_server, /rules_characters, /rules_roleplay, /server_info |
This project is provided as-is. Feel free to adapt for your own community with attribution.
Last Updated: April 2026 · Bot Version: 3.0 · Built with discord.py 2.3+