Welcome & Project Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Poixpixel Discord Bot is a TypeScript-based application built on the discord.js framework, designed to provide a comprehensive suite of features for Discord server management and engagement. The project integrates multiple backend services, including PostgreSQL for persistent data storage and Redis for high-performance caching. Its scope encompasses modular command handling, automated moderation, leveling systems, and a structured event-driven architecture.
The project is currently in a development state and is not considered production-ready. It utilizes modern development tools such as Yarn (managed via Corepack), Drizzle ORM for database interactions, and Winston for structured logging with optional OpenTelemetry integration.
Sources: README.md:3-5, CONTRIBUTING.md:14-25, package.json:34-45
Core Architecture
The bot follows a modular architecture where the entry point initializes an ExtendedClient. This client manages command discovery, event routing, and service connections. The application is designed to be highly maintainable by separating command logic, database functions, and utility helpers into distinct directory structures.
The diagram shows the high-level initialization flow and the directory-based command discovery system.
Technology Stack
The project leverages the following core technologies:
| Component | Technology | Description |
|---|---|---|
| Runtime | Node.js (>=22.0.0) | The primary JavaScript execution environment. |
| Language | TypeScript | Provides static typing and modern JavaScript features. |
| Discord API | discord.js (^14.25.1) | The main library for interacting with the Discord Gateway. |
| Database ORM | Drizzle ORM | Used for type-safe SQL queries and migrations. |
| Database | PostgreSQL | Persistent storage for users, levels, and moderation logs. |
| Caching | Redis | Used for transient data and performance optimization. |
| Logging | Winston | Provides structured logging with multiple transports. |
Sources: package.json:34-75, CONTRIBUTING.md:30-36
Functional Modules
The bot's functionality is organized into specialized categories, accessible via slash commands. The system implements a permission-based access model, ensuring that sensitive administrative and moderation tools are restricted to authorized personnel.
Command Categories
Commands are auto-discovered from the src/commands/ directory and categorized as follows:
- Fun: Includes leveling, achievements, counting games, and facts.
- Moderation: Tools for banning, kicking, muting, and warning users.
- Utility: Includes configuration management, help menus, and backend service control.
- Testing: Internal commands used during development to simulate join/leave events.
Sources: src/commands/util/help.ts:187-217, CONTRIBUTING.md:231-236
Leveling and Achievements
The bot features a sophisticated leveling system that awards XP based on message activity. Leveling logic is gated by a cooldown (default 45s) to prevent spam. Achievements are earned based on specific thresholds (e.g., message count, levels reached) and can provide rewards such as XP or roles.
Logic flow for the message-based XP and achievement system.
Sources: src/util/levelingSystem.ts:133-176, src/commands/util/manage-achievement.ts:16-52, config.example.json:104-113
Configuration and Deployment
Configuration is managed via a config.json file (based on config.example.json). This file defines everything from API tokens to channel IDs for specific features like logs or counting.
Configuration Structure
| Section | Purpose | Key Fields |
|---|---|---|
database | DB Connection | poolingDbConnectionString, directDbConnectionString |
channels | Functional Routing | welcome, logs, counting, advancements |
roles | Permissions/Leveling | joinRoles, levelRoles, staffRoles |
counting | Game Settings | mistakeThreshold, maxWarnings, autoBanDuration |
Sources: config.example.json:14-115
Development Workflow
The project provides several scripts for lifecycle management:
yarn dev: Compiles and starts the bot with command deployment.yarn no-deploy: Starts the bot without re-deploying slash commands to Discord.yarn start: Production start using PM2.yarn lint: Runs ESLint and TypeScript type checks.
Sources: package.json:12-23, README.md:16-36
Conclusion
The Poixpixel Discord Bot project is a robust, modular framework for building interactive community tools. By utilizing a strong TypeScript foundation, Drizzle ORM, and integrated caching, it provides a scalable architecture for server management. While still in development, the project maintains high standards for code quality through strict linting, conventional commits, and a structured contribution process.
Sources: CONTRIBUTING.md:143-162, README.md:3-5