Groundsman Discord Bot (Python + discord.py)

A Discord verification bot built with Python and discord.py that:

1. Keeps a persistent verification panel in channel A.
2. Shows two buttons: Yes and No.
3. Sends an ephemeral message for No.
4. Opens a modal for Yes with check-in questions.
5. Creates a review thread in channel B after modal submission.
6. Lets moderators choose Kudos or Poopers from a dropdown.
7. Sends approved (Kudos) records to channel C for logs.
8. Logs runtime events to logs/bot.log.

---

Tech Stack

• Python 3.10+ recommended
• discord.py
• Discord API (through discord.py)
• pytest for lightweight tests

---

Project Structure

• bot.py - Main bot implementation, event handling, modal, and logging setup
• requirements.txt - Python dependencies
• .env.example - Environment variable template for bot token
• tests/test_bot.py - Basic automated tests
• CHANGELOG.md - Ordered record of project changes
• logs/bot.log - Runtime log file (created automatically at startup)

---

How The Bot Works

Event flow

1. Bot starts and connects to Discord.
2. In on_ready, bot ensures channel A contains a verification panel embed with a persistent View.
3. User clicks No:
   • Bot sends an ephemeral response visible only to that user.
4. User clicks Yes:
   • Bot opens HowAreYouModal.
5. User submits modal:
   • Bot stores the submission in memory.
   • Bot creates a thread in channel B named with the user's ID.
   • Bot posts review UI (dropdown with Kudos / Poopers) in that thread.
6. Moderator selects dropdown option:
   • If Kudos, bot forwards submission details to channel C.
   • Bot replies ephemerally to the moderator with decision status.

---

Bot Architecture

Core components

• GroundsmanBot(commands.Bot)
  • Subclass of commands.Bot
  • Handles lifecycle events (setup_hook, on_ready)
  • Registers persistent UI with add_view(...)
  • Maintains in-memory submissions map for review decisions
• VerificationPanelView(discord.ui.View)
  • Persistent UI attached to the channel A verification message
  • Contains Yes and No buttons
  • Uses custom component IDs so callbacks survive restarts
• HowAreYouModal(discord.ui.Modal)
  • Modal form shown when user clicks Yes
  • Contains two text fields:
    • Required mood input
    • Optional details input
  • Handles submission in on_submit and creates review thread in channel B
• ReviewView(discord.ui.View) + ReviewSelect(discord.ui.Select)
  • Mod-only moderation UI in channel B thread
  • Dropdown decisions: Kudos or Poopers
  • Kudos forwards a full embed log to channel C
• configure_logging()
  • Creates logs/ directory and logs/bot.log
  • Writes timestamped logs to file and console
• required_env_int(...)
  • Validates required channel ID environment variables

Discord.py API concepts used

• discord.ui.View
  • Container for interactive UI components (buttons/selects)
  • Supports persistent components with timeout=None
• discord.ui.Button
  • Clickable action component
  • Used for Yes/No choices in channel A
• discord.ui.Modal + discord.ui.TextInput
  • Pop-up form for collecting structured user input
• discord.ui.Select
  • Dropdown component for moderator decision workflow
• interaction.response.send_message(..., ephemeral=True)
  • Sends per-user temporary responses only visible to clicker
• TextChannel.create_thread(...)
  • Creates per-submission mod review thread in channel B
• Bot.add_view(...)
  • Registers persistent component handlers on startup

Runtime logging

The bot logs:

• Startup and login events
• Verification panel creation/update status
• Modal submission metadata
• Moderator decisions

Log output goes to:

• Console (stdout)
• logs/bot.log

---

Setup Instructions

1) Create and configure a Discord application

1. Go to the Discord Developer Portal.
2. Create a new application.
3. Under Bot, create a bot user.
4. Copy the bot token
5. No privileged message intent is required for this button-first workflow.

2) Invite bot to your server

1. In OAuth2 URL generator:
   • Scope: bot
   • Bot permissions (minimum): Send Messages, Read Message History, View Channels, Create Public Threads, Send Messages in Threads
2. Open generated URL and add bot to your test server.

3) Local environment

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Create .env from template:

cp .env.example .env

Set token:

DISCORD_BOT_TOKEN=your_real_token_here

You can export it manually:

export DISCORD_BOT_TOKEN="your_real_token_here"

Set channel IDs:

export CHANNEL_A_ID="channel_id_for_verification_panel"
export CHANNEL_B_ID="channel_id_for_mod_review_threads"
export CHANNEL_C_ID="channel_id_for_approved_logs"

---

Run The Bot

python bot.py

Expected startup output:

• "Logged in as ..."
• logs/bot.log created automatically

---

Test

Run unit tests:

pytest -q

Manual test in Discord:

1. Start bot and confirm panel message appears in channel A.
2. Click No and verify an ephemeral message appears only for you.
3. Click Yes and verify modal opens with both questions.
4. Submit modal and verify:
   • Ephemeral confirmation to user
   • Thread is created in channel B with user ID in thread name
   • Dropdown (Kudos / Poopers) appears in thread
5. As moderator, choose Kudos and verify a log embed is posted to channel C.

---

Change Tracking

All project changes should be appended to CHANGELOG.md in date order.