Moderation System
Relevant source files
The following files were used as context for generating this wiki page:
The Moderation System in the Poixpixel Discord Bot provides a robust framework for managing user behavior within a guild. It encompasses standard administrative actions such as banning, kicking, and muting, alongside specialized sub-systems for warning tracking and automated enforcement in specific modules like the counting channel.
The system is built on a multi-tier architecture involving command interfaces (Slash Commands), a database layer for persistent history, and an audit logging utility to ensure transparency. It supports both permanent and temporary sanctions, utilizing scheduled timeouts to automate the expiration of mutes and bans.
System Architecture
The moderation architecture follows a request-execute-log flow. Commands interact with the Discord API to apply sanctions and simultaneously update the PostgreSQL database via Drizzle ORM to maintain a permanent record of user infractions.
The diagram above illustrates the typical flow of a moderation action from the initial command to final logging and storage.
Sources: src/commands/util/help.ts, src/db/functions/moderationFunctions.ts:25-50, src/util/logging/logAction.ts:40-60
Core Moderation Actions
The system supports several primary moderation actions. Each action is tracked with specific metadata including the moderator's ID, the reason, and optional duration for temporary penalties.
Primary Command Actions
| Action | Purpose | Persistence |
|---|---|---|
| Ban | Removes a user and prevents re-entry | Database & Discord |
| Kick | Removes a user from the guild | Database |
| Mute | Prevents a user from speaking (Timeouts) | Database & Discord |
| Warn | Records an infraction without immediate penalty | Database |
| Purge | Mass deletes messages in a channel | Audit Logs |
Sources: src/commands/util/help.ts:220-230, src/util/logging/logAction.ts:65-80
Automated Sanction Management
The bot includes logic to handle "temporary" sanctions. When a mute or ban is issued with a duration, the system calculates an expiration timestamp. Upon bot startup, it reloads these active sanctions from the database to ensure timers are resumed.
This sequence shows how the bot ensures temporary sanctions expire correctly even across restarts.
Sources: src/util/helpers.ts:250-280, src/util/helpers.ts:340-370
Audit Logging
The system uses a centralized logAction function to report all moderation events to a designated log channel. This includes not only manual commands but also message deletions, member joins/leaves, and role updates.
- Moderation Logs: Capture target user, moderator, reason, and duration.
- Purge Logs: Generate a temporary
.txtfile containing a full transcript of deleted messages, which is uploaded as an attachment. - Visual Indicators: Actions are color-coded (e.g., Red for Bans, Orange for Mutes) to allow quick scanning by staff.
Sources: src/util/logging/logAction.ts:40-100, src/util/logging/logAction.ts:130-150
Counting Channel Moderation
The Moderation System extends into functional modules, specifically the Counting system. It features a unique "Mistake Tracker" that escalates penalties for repeated errors.
Enforcement Logic
- Mistake: A single incorrect count.
- Warning: Issued after a threshold of mistakes (defined in configuration) is met.
- Automated Ban: Triggered when the maximum number of warnings is reached. This prevents the user from participating in the counting channel for a specific duration or permanently.
The flow illustrates the escalation from a simple mistake to an automated channel ban.
Sources: src/util/counting/countingManager.ts:480-550
Data Persistence & History
Moderation history is stored in the moderationTable. This allows staff to view a user's full history using the /user-info command, which displays total warnings, mutes, and bans alongside recent details.
Database Fields
| Field | Type | Description |
|---|---|---|
discordId | String | The ID of the sanctioned user |
moderatorDiscordId | String | The ID of the staff member |
action | String | Type of moderation (e.g., 'ban', 'mute', 'warning') |
reason | String | Provided reason for the action |
active | Boolean | Whether the sanction is currently in effect |
expiresAt | Date | Expiration timestamp for temporary actions |
Sources: src/db/functions/moderationFunctions.ts:25-45, src/commands/util/user-info.ts:50-100
Summary
The Moderation System serves as the primary toolset for server administration, combining manual staff commands with automated enforcement logic. By integrating persistent database storage, real-time audit logging, and automated sanction expiration, the system provides a comprehensive solution for maintaining order and accountability within the Discord guild environment.