Celestine

Celestine (hereinafter the “Application”) is a comprehensive paid moderation bot for Discord servers, built with TypeScript and Discord.js. The Application provides advanced moderation tools, automated security features, leveling systems, birthday celebrations, and comprehensive logging capabilities. It includes a web server for health monitoring and metrics, integrates with MongoDB for data persistence, and features a subscription-based access model.

1. User Documentation

Core Features

Moderation Commands

• /ban - Ban users from the server with optional message pruning and evidence links
• /unban - Remove bans from users with logging and notification systems
• /kick - Remove users from the server temporarily
• /mute - Temporarily restrict user communication with duration controls (minutes, hours, days, weeks)
• /unmute - Remove communication restrictions from users
• /warn - Issue warnings to users with evidence tracking
• /note - Add private moderation notes about users
• /softban - Ban and immediately unban to clean up user messages
• /massban - Ban multiple users at once using a list of user IDs

Server Management

• /lockdown - Lock text channels to prevent message sending
• /unlock - Remove lockdown restrictions from channels
• /prune - Bulk delete messages from channels
• /secure - Toggle server-wide DM and invite restrictions for new members

Configuration System

• /config list - View current server configuration
• /config logging - Set up moderation and event log channels
• /config invite-link - Configure invite links sent to kicked users
• /config appeal-link - Set ban appeal links for banned users
• /config roles - Toggle roles as self-assignable
• /config join-role - Set automatic role assignment for new members
• /config birthday-channel - Configure birthday celebration channel

User Experience Features

• /rank - View personal level and XP in the server
• /leaderboard - Browse server level rankings with pagination
• /profile - Customise profile appearance (avatar, colours, background)
• /role - Self-assign permitted roles
• /birthday - Set birthday for automatic celebrations
• /level-role - Configure roles automatically assigned at specific levels

Administrative Tools

• /cases - View specific moderation case details
• /history - View comprehensive user moderation history
• /help - Get bot information, version details, and support links
• /ping - Check bot latency and database connectivity

Context Menu Actions

• Report Message - Right-click context menu to report problematic messages

Automated Features

Leveling System

• Automatic XP gain from message activity with anti-spam cooldowns
• Customisable level roles that auto-assign at specified levels
• Visual profile cards with customisable backgrounds and colours
• Server leaderboards with pagination

Security & Moderation

• Automatic detection and removal of known spam domains
• Automatic muting of compromised accounts posting malicious links
• Comprehensive audit logging for all moderation actions
• Member join/leave tracking with configurable logging

Event Logging

• Message edit/delete tracking with content preservation
• Voice channel activity monitoring
• Member update tracking (nickname, role changes)
• Moderation action logging with evidence and case numbers

Birthday System

• Automatic birthday wishes in designated channels
• Scheduled daily birthday checks
• User-configurable birthday dates with validation

Access Control

• Subscription-based access model ($5/month)
• Permission-based command restrictions
• Moderator role validation for administrative commands
• Granular configuration permissions

This section is for those interacting with a live instance of the Application.

2. Technical Documentation

Architecture Overview

Celestine is built as a modern Discord bot using:

• Runtime: Node.js with TypeScript
• Discord Library: Discord.js v14
• Database: MongoDB with Prisma ORM
• Web Server: Express.js for health endpoints
• Monitoring: Prometheus metrics integration
• Scheduling: Node-schedule for automated tasks

Project Structure

src/
├── commands/           # Slash command implementations
├── contexts/          # Context menu command handlers
├── events/            # Discord event handlers
│   ├── client/        # Bot lifecycle events
│   ├── guild/         # Server-related events
│   ├── interaction/   # Command interaction handling
│   ├── member/        # Member join/leave/update events
│   ├── message/       # Message create/edit/delete events
│   ├── thread/        # Thread-related events
│   └── voice/         # Voice state change events
├── interfaces/        # TypeScript type definitions
├── modules/           # Reusable business logic
│   ├── commands/      # Command-specific modules
│   ├── data/          # Database interaction modules
│   ├── events/        # Event processing modules
│   ├── interactions/  # Interaction handling modules
│   ├── modals/        # Modal form handlers
│   └── subcommands/   # Subcommand implementations
├── server/            # Web server and health endpoints
├── utils/             # Utility functions and helpers
├── config/            # Configuration constants
└── database/          # Database connection setup

Database Schema

The application uses MongoDB with the following key models:

Core Data Models

• cases - Moderation case tracking with evidence and timestamps
• configs - Per-server configuration settings
• levels - User XP and level progression data
• levelRoles - Automatic role assignments by level
• roles - Self-assignable role permissions
• birthdays - User birthday tracking
• entitlements - Server subscription management
• security - Server security settings (DM/invite restrictions)

Key Features of Data Layer

• Unique constraints for data integrity
• Indexed queries for performance
• Automatic relationship management
• Soft deletion support for case history

Development Setup

Prerequisites

• Node.js 18+
• MongoDB instance
• Discord Bot Token
• TypeScript compiler

Environment Variables

BOT_TOKEN=<discord_bot_token>
MONGO_URI=<mongodb_connection_string>
DEBUG_HOOK=<discord_webhook_url>

Build Process

npm install          # Install dependencies
npm run prebuild     # Clean build directory and generate Prisma client
npm run build        # Compile TypeScript to JavaScript
npm start           # Run the bot

Development Scripts

• npm run lint - ESLint and Prettier validation
• npm run audit - Dependency and code analysis with Knip
• npm run scan - SonarCloud quality analysis

Web Server Endpoints

The bot includes an Express.js server providing:

Health & Status

• GET / - HTML landing page with bot information and invite links
• GET /metrics - Prometheus metrics endpoint for monitoring

Integration Points

Discord API

• Slash commands and context menus
• Webhook integrations for logging
• Permission validation
• Message content scanning

External Services

• GitHub integration for version tracking
• Prometheus metrics collection
• MongoDB Atlas for cloud database
• 1Password for secrets management

Monitoring & Observability

Logging

• Winston-based structured logging
• Error tracking with unique identifiers
• Debug message routing to Discord webhooks
• Comprehensive audit trails

Metrics

• Prometheus integration for performance monitoring
• Database latency tracking
• Command usage statistics
• Server count and member tracking

Security Considerations

Access Control

• Subscription validation for server access
• Permission-based command restrictions
• Rate limiting through Discord.js built-ins
• Input validation and sanitisation

Data Protection

• Encrypted database connections
• Secure environment variable handling
• Minimal data retention policies
• Privacy-conscious logging practices

This section is for those interested in running their own instance of the Application.

3. Legal Documentation

Subscription Model

Celestine operates as a paid service with a $5/month subscription fee per Discord server. This subscription model ensures:

• Sustainable development and maintenance
• Priority support for subscribers
• Regular feature updates and improvements
• Infrastructure costs coverage

Data Handling

The Application processes and stores:

• Discord user IDs and server IDs
• Message content for moderation purposes (temporary)
• User-configured profile information
• Moderation case history and evidence links
• Server configuration preferences

Service Availability

• Best-effort uptime with monitoring systems
• Planned maintenance notifications
• Support through designated Discord server
• Community-driven feedback and feature requests

4. Contributing Documentation

Development Workflow

Code Standards

• TypeScript for type safety
• ESLint and Prettier for code formatting
• Comprehensive error handling with unique error IDs
• JSDoc documentation for public interfaces

Testing Strategy

• Integration testing with Discord API
• Database transaction testing
• Command validation testing
• Performance benchmarking

Pull Request Process

1. Fork the repository
2. Create feature branch from main
3. Implement changes with tests
4. Ensure linting and build passes
5. Submit PR with detailed description
6. Address review feedback
7. Merge after approval

Architecture Decisions

• Modular command structure for maintainability
• Event-driven architecture for real-time responses
• Database abstraction through Prisma ORM
• Configuration-driven behaviour customisation

Extension Points

Adding New Commands

1. Create command file in src/commands/
2. Implement Command interface
3. Add to command loader
4. Update permissions if needed
5. Add documentation

Custom Event Handlers

1. Create handler in appropriate src/events/ subdirectory
2. Implement error handling
3. Add to event registration system
4. Test with Discord API

Database Schema Changes

1. Update Prisma schema
2. Generate migration
3. Test migration on development database
4. Update TypeScript interfaces
5. Implement backward compatibility