---
title: 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
```bash
TOKEN=<discord_bot_token>
MONGO_URI=<mongodb_connection_string>
DEBUG_HOOK=<discord_webhook_url>
DEV_MODE=<boolean>
```

#### Build Process
```bash
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 sanitization

#### 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

