TEST Squadron Discord Bot

Welcome to the TEST Squadron Discord Bot repository. This bot helps manage user verification within our Discord server and provides advanced voice channel management features. The codebase has been optimized for both human maintainability and AI agent comprehension.

🚀 Features

• Token-Based Verification: Users receive a unique token to verify their membership.
• Role Assignment: Automatically assigns roles based on verification status.
• Cooldown System: Limits verification attempts to prevent spam and abuse.
• Voice Channel Management: Users can create and customize their voice channels via bot commands (the bot retains channel management permissions; users manage through the bot).
• Activity Metrics Dashboard: Tracks server-wide and per-user voice time (all voice channels), message counts, and game activity with leaderboard/time-series views. Dashboard access requires Discord Manager or higher. No message content is ever read or stored. See PRIVACY.md for data handling details.
• Persistent Settings: User channel settings are stored in a database for a consistent experience.
• Interactive Modals and Views: Provides an interactive user experience with Discord's UI components.
• Persistent Verification Message: The bot keeps a single verification message in the verification channel — it stores the message ID in verification_message_id.json and will reuse that message instead of creating duplicates. It does not currently delete old messages on startup.
• Error Handling and Logging: Gracefully handles permission issues and logs errors for debugging.
• 🤖 AI-Agent Optimizations: Structured prompts, schemas, defensive retry patterns, and comprehensive type safety for AI development assistance.

🏗️ Architecture Overview

Core Components

• bot.py: The main bot script initializing the bot, loading environment variables, configuration, and setting up logging.
• config/: Configuration management with type-safe loading
  • config.yaml: Stores core runtime settings (prefixes, rate limits, org metadata). Role mappings now live in the database and are managed via the Web Dashboard.
• cogs/: Discord.py command modules
  • verification.py: Handles user verification process
  • voice.py: Voice channel management system
  • admin.py: Administrative commands
• helpers/: Utility modules for common functionality
  • http_helper.py: HTTP client with retry mechanisms
  • embeds.py: Discord embed creation utilities with factory patterns
  • discord_reply.py: Unified interaction response helpers
  • permissions_helper.py: Permission level checking with hierarchy support
  • error_messages.py: User-facing error message formatting
• services/db/: Database access layer
  • repository.py: BaseRepository pattern for unified DB access
  • database.py: Connection management and schema
• docs/: Developer documentation
  • DRY_PATTERNS.md: Code patterns and utilities reference
• prompts/: AI-agent friendly templates and schemas
  • schemas/: JSON schemas for data validation
  • messages/: User-facing message templates
  • system/: Development and debugging templates
• verification/: RSI verification logic
• config/: Configuration management
  • config_loader.py: Handles loading and providing access to configuration data
  • config.yaml: Runtime settings (rate limits, voice settings, RSI config)
• requirements.txt: Lists the dependencies required for the project
• SETUP.md: Production deployment guide
• VS_CODE_SETUP.md: Local development setup guide

🛠️ Getting Started

Discord Bot Permissions

The bot requires specific Discord permissions to function properly. Do not grant Administrator permissions - instead, grant only these specific permissions for security:

Required Permissions:

• View Channels - Read messages and see channels
• Send Messages - Send responses and notifications
• Embed Links - Send rich embed messages
• Read Message History - Access previous messages for context
• Use Slash Commands - Register and respond to slash commands
• Manage Roles - Assign verification and member roles
• Manage Channels - Create/delete voice channels and manage categories
• Connect - Connect to voice channels
• Move Members - Move users between voice channels
• Change Nickname - Update user nicknames during verification
• Manage Nicknames - Update other users' nicknames

Permission Setup:

1. Go to your Discord server settings
2. Navigate to Roles → [Bot Role]
3. Enable only the permissions listed above
4. Ensure the bot's role is positioned high enough to manage the roles it needs to assign
5. For voice categories: Right-click the voice category → Edit Category → Permissions → Add bot role with "Manage Channels" permission

Required Gateway Intents (Discord Developer Portal)

Metrics collection depends on privileged intents. In Discord Developer Portal → Bot:

• Enable SERVER MEMBERS INTENT
• Enable PRESENCE INTENT (required for game/activity metrics)

Note: The messages intent (non-privileged) is used to receive message events for counting. The MESSAGE CONTENT privileged intent is not required — the bot only counts messages, it never reads their content.

Voice time metrics are tracked from voice state events across all voice channels, not just channels created by the bot.

Privacy Note: Metrics data is retained for a configurable period (default 90 days, set metrics.retention_days in config/config.yaml). Per-user deletion is available via the admin dashboard API. Excluded channels configured in guild settings are honoured during both live collection and startup backfill. See PRIVACY.md for full data handling policy.

Role Configuration:

Configure role access levels in the Web Dashboard → Guild Settings → Roles. Role lists are stored in the database (per guild) and kept in sync with Discord role IDs.

Web Dashboard Access:

• Bot Admin & Moderator: Full access (user recheck, reset voice, manage settings)
• Discord Manager+: Metrics dashboard access (view activity leaderboards, time-series, per-user detail)
• Staff & Higher: Read-only access (view dashboards, search users, statistics — excludes metrics)
• All role levels require at least one guild where they have the configured role

Admin Commands

The bot includes several administrative commands for configuration and management. All admin commands require users to have the appropriate role level configured via the Web Dashboard (DB-backed roles; see Permission System).

💡 Live Command Discovery: For the most up-to-date list of available commands, use /help in Discord or /status for detailed bot information. Commands listed below represent the core functionality but may not reflect the latest additions or changes.

About Command

• /about (ephemeral): Shows bot purpose, current version, privacy summary, user rights, and support contact. Uses centralized metadata in utils/about_metadata.py (update version/contact during releases). Full policy: PRIVACY.md.
• /privacy (ephemeral): Shows privacy/legal basis summary, user rights, request steps (access/correction/deletion/objection), retention summary, support contact, and PRIVACY.md policy link.

Dashboard Command

• /dashboard (ephemeral, Staff+): Provides a link to the Web Admin Dashboard. URL configured in web_dashboard.url (config.yaml). Dashboard enforces role-based permissions for guild management, user lookup, and statistics.

General Admin Commands

Command	Description	Required Role	Usage
/status	Show detailed bot health and status information	Bot Admin	/status detailed:true
/reset-all	Reset verification timers for all members	Bot Admin	/reset-all
/reset-user	Reset verification timer for a specific user	Moderator+	/reset-user member:@username
/verify check-user	Check or recheck verification status for a single user	Moderator+	/verify check-user member:@user action:check
/verify check-members	Check or recheck verification status for multiple users	Moderator+	/verify check-members members:"@user1 @user2" action:check
/verify check-channel	Check or recheck verification status for users in a voice channel	Moderator+	/verify check-channel channel:#General-Voice action:check
/verify check-voice	Check or recheck verification status for all users in active voice channels	Moderator+	/verify check-voice action:check

Note: Log viewing and guild configuration are now managed through the Web Admin dashboard.

User Verification Lookup Command

Command	Description	Required Role	Usage
/check user	Show detailed verification info for a user: RSI handle, main org, affiliate orgs, verification/join dates, all with clickable links. Output is a clean, table-style embed for staff review.	Staff+	/check user member:@username

Example Output:

┌────────────────────┬────────────────────────────────────────────────────────────┐
│ RSI Handle         │ [HandleName](RSI Profile URL)                              │
│ Main Org           │ [ORG_TAG](Main Org URL)                                    │
│ Affiliate Orgs     │ [ORG1](Org1 URL), [ORG2](Org2 URL)                         │
│ Verified At        │ 2025-12-04 13:00 UTC                                       │
│ Joined Server      │ 2024-11-01 18:22 UTC                                       │
└────────────────────┴────────────────────────────────────────────────────────────┘

All fields are clickable and presented side-by-side for clarity.

Voice Admin Commands (/voice group)

Command	Description	Required Role	Usage
/voice setup	Set up voice channel system (create JTC channels and category)	Bot Admin	/voice setup category:#Voice-Channels num_channels:2
/voice admin reset	Reset voice data with modern safety features	Moderator+	/voice admin reset scope:user member:@username or /voice admin reset scope:all confirm:YES
/voice admin_list	View saved voice channel settings for a user	Staff+	/voice admin_list user:@username

User Voice Commands (/voice group)

Command	Description	Available To	Usage
/voice list	List all custom permissions and settings in your voice channel	Voice channel owners	/voice list
/voice claim	Claim ownership of a voice channel if the original owner left	All users	/voice claim
/voice transfer	Transfer ownership of your voice channel to another user	Voice channel owners	/voice transfer user:@username
/voice help	Show help information for voice commands	All users	/voice help
/voice owner	List all voice channels managed by the bot and their owners	Any member	/voice owner

Note: Voice channel settings are automatically presented via an interactive interface when you create a channel. Use /voice list to view your current settings.

Configuration Examples

Setting Voice Cooldown:

/set-config key:"voice.cooldown_seconds" value:"30"

Setting Custom Voice Settings:

/set-config key:"voice.max_channels_per_user" value:"3"
/set-config key:"voice.channel_name_template" value:"{user}'s Channel"

Viewing Current Configuration:

/guild-config

Setting Up Voice System:

/voice setup category:#Voice-Channels num_channels:3

Verification Status Check Examples

The /verify command group provides verification status checking and forced reverification with four specialized commands:

Single User Check

Check or recheck a single user:

/verify check-user member:@user action:check
/verify check-user member:@user action:recheck

Multiple Users Check

Check or recheck multiple users by mentions or IDs:

/verify check-members members:"@user1 @user2 123456789012345678" action:check
/verify check-members members:"@user1 @user2" action:recheck

Voice Channel Check

Check or recheck all users in a specific voice channel:

/verify check-channel channel:#General-Voice action:check
/verify check-channel channel:#General-Voice action:recheck

All Active Voice Channels Check

Check or recheck all users in any active voice channel:

/verify check-voice action:check
/verify check-voice action:recheck

Command Options:

• member (check-user only) - Single user to check
• members (check-members only) - User mentions or IDs (can specify multiple)
• channel (check-channel only) - Voice channel to check
• action (all commands) - Either check (read-only status) or recheck (force reverification). Defaults to check.

Behavior:

• In check mode: Returns verification status with RSI org details. Queues a bulk verification job to check status.
• In recheck mode: Forces user reverification, updating roles and nicknames as needed. Logs changes to leadership chat.
• All checks automatically include detailed RSI organization verification (main and affiliate orgs).
• Respects rate limiting for user-initiated rechecks; bypasses for admins with elevated permissions.
• Respects the auto_recheck.batch.max_users_per_run configuration limit (default: 50 users per check).

CSV Export: Results are exported to CSV with the following columns:

• user_id, username, rsi_handle - Basic user identification
• membership_status - Derived at query time (not stored as a column): main, affiliate, non_member, unknown
• last_updated - Unix timestamp of last verification
• voice_channel - Current voice channel name (if in voice)
• rsi_status, rsi_checked_at, rsi_error - RSI verification data (always included)
• main_orgs, affiliate_orgs - Semicolon-separated lists of user's organizations

Permission System

Both the Discord bot and web dashboard use a hierarchical role-based permission system rather than Discord's built-in Administrator permission for security:

• Role lists are stored in the database per guild and edited through the Web Dashboard (Guild Settings → Roles). Changes stay aligned with actual Discord role IDs.
• Delegation policies (for controlled role grants) will live under the roles.delegation_policies key in guild settings.

Role Hierarchy (Highest to Lowest Privilege):

1. Bot Owner - Full system access (user must be bot owner in config)
2. Bot Admin - Full administrative access to all functions
3. Discord Manager - Advanced administrative capabilities
4. Moderator - Moderation and user management capabilities
5. Staff - Read-only access to dashboards and status information
6. Regular Users - Access to user-facing commands and voice channel management only

Permission Examples:

• Bot Admin: Can recheck users, reset voice settings, manage guild configuration, access logs via Web Admin
• Discord Manager: Metrics dashboard (leaderboards, time-series, per-user detail, per-user deletion)
• Moderator: Can recheck users, manage user-specific settings
• Staff: Can view dashboards, search users, monitor statistics (read-only; no metrics access)
• Regular Users: Can manage their own voice channels, request verification

Permission Checks:

• Commands and API endpoints check for specific role IDs configured in config/config.yaml
• Web dashboard enforces role validation on every request with TTL-based caching (30 second default)
• Live Discord role validation: Access is immediately revoked if user's Discord roles change
• Multiple roles can be assigned the same permission level
• No Discord Administrator permission is required or recommended

Security Benefits:

• Principle of Least Privilege: Users only get necessary permissions
• Granular Control: Different roles can have different permission levels
• Audit Trail: All admin actions are logged with user information
• No Overreach: Bot cannot perform server-wide admin actions

For detailed setup instructions, refer to SETUP.md (production deployment) or VS_CODE_SETUP.md (local development) in the repository.

📄 Documentation

Comprehensive documentation is available and includes:

• Modules Documentation: Detailed explanations of each module and its components.
• Usage Instructions: Step-by-step guides on how to use the bot.
• Setup Instructions: Instructions on setting up the bot locally.
• Troubleshooting: Solutions to common issues.

Developer documentation source is included in the docs/ directory (markdown files). The generated Sphinx HTML (docs/build/html/...) is not committed to this repository.

If you prefer to view HTML docs locally, build them from the Sphinx sources on your machine (see "Building docs locally" below) — otherwise read the markdown files in docs/.

Developer Scripts

Tools in scripts/ are optional utilities for debugging and maintenance. They are not used during normal bot or backend operation, and runtime modules should not import them.

🌐 Web Admin Dashboard

The bot includes a comprehensive web admin dashboard for managing and monitoring bot operations from a browser interface.

Features

• Discord OAuth2 Authentication: Secure login with your Discord account
• Live Role-Based Access Control: Access enforced based on Discord roles
  • Bot Admin & Moderator: Full administrative access (user recheck, voice reset, logs export)
  • Discord Manager+: Metrics dashboard access (leaderboards, time-series, per-user detail and deletion)
  • Staff & Higher: Read-only dashboard access (statistics, user search, voice management — excludes metrics)
  • Regular Users: No dashboard access
• Live Role Validation: Access immediately revoked if Discord roles change (TTL: 30 seconds)
• Dashboard Overview: View verification statistics and active voice channels
• User Management: Search, recheck, and export verification records by user ID, RSI handle, or community moniker
• Voice Channel Management: View and search voice channels by user ID, with moderator-level reset capabilities
• Permission-Aware UI: Buttons hidden for users without required permissions

Quick Start

1. Set up Discord OAuth2 credentials in .env (see SETUP.md for environment variable details)
2. Start the backend:

   cd web/backend
   pip install -r requirements.txt
   uvicorn app:app --reload --port 8081

3. Start the frontend (in a new terminal):

   cd web/frontend
   npm install
   npm run dev

4. Open your browser to http://localhost:5173 and login with Discord

For detailed setup instructions, architecture details, and troubleshooting, see SETUP.md.

VS Code Debugging

Pre-configured launch configurations are available:

• 🌐 Web Admin Only: Runs backend + frontend together
• 🚀 Full Stack: Runs bot + backend + frontend together

Access via Run and Debug panel (Ctrl+Shift+D) in VS Code.