---
title: Boost Monitor
---

Boost Monitor (hereinafter the "Application") is a Discord bot that automatically manages special roles for server boosters. The Application monitors server members and removes booster-exclusive roles (such as custom colour roles) when a member stops boosting the server.

## 1. User Documentation

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

### Overview

The Discord Boost Monitor operates automatically in the background of your Discord server. It requires no direct user interaction once configured by server administrators.

### How It Works

1. **Automatic Monitoring**: The bot monitors all member updates in the Discord server
2. **Boost Detection**: When a member's boost status changes, the bot checks if they still have the server booster role
3. **Role Management**: If a member no longer has the booster role, the bot automatically removes any configured booster-exclusive roles (such as custom colour roles)

### Key Features

- **Automated Role Removal**: No manual intervention needed when members stop boosting
- **Configurable Roles**: Server-specific booster and colour role IDs can be configured
- **Status Monitoring**: Health check endpoint available at the bot's web interface
- **Debug Webhooks**: Sends status updates and error reports to configured Discord webhooks

### Accessing the Bot

The bot runs as a background service and does not have traditional user-facing commands. Server administrators can monitor its status through:

- **Web Interface**: HTTPS endpoint showing bot status and information
- **Debug Webhook**: Real-time updates sent to configured Discord webhook
- **Server Logs**: Winston-based logging for troubleshooting

## 2. Technical Documentation

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

### Prerequisites

- **Node.js**: Version 22 or higher
- **pnpm**: Version 9 or higher
- **Discord Bot Token**: From the Discord Developer Portal
- **SSL Certificates**: For HTTPS server (Let's Encrypt or similar)
- **Sentry Account** (optional): For error tracking

### Installation

1. Clone the repository:
   ```bash
   git clone https://git.nhcarrigan.com/NHCarrigan/boost-monitor.git
   cd oogie-woogie-boostie-woostie
   ```

2. Install dependencies:
   ```bash
   pnpm install
   ```

3. Configure environment variables by creating a `.env` file:
   ```bash
   cp sample.env .env
   ```

4. Edit `.env` with your configuration:
   ```sh
   DISCORD_TOKEN="your-discord-bot-token"
   SENTRY_DSN="your-sentry-dsn"
   DEBUG_HOOK="your-discord-webhook-url"
   ```

### Configuration

#### Role Configuration

Edit `src/config/roles.ts` to configure your server-specific role IDs:

- **colourRoles**: Array of role IDs that should be removed when a member stops boosting (src/config/roles.ts:1-10)
- **boosterRole**: The ID of your server's booster role (src/config/roles.ts:12)

Example:
```typescript
export const colourRoles = [
  "883281643098484736", // Red role
  "883283836887261204", // Blue role
  // Add your colour role IDs here
];

export const boosterRole = "712431541531181177"; // Your booster role ID
```

#### SSL Certificates

The bot expects SSL certificates at the following locations:
- Certificate: `/etc/letsencrypt/live/oogie.nhcarrigan.com/cert.pem`
- Private Key: `/etc/letsencrypt/live/oogie.nhcarrigan.com/privkey.pem`

Update the paths in `src/server/serve.ts:18-22` if your certificates are located elsewhere.

### Building and Running

1. Build the TypeScript code:
   ```bash
   pnpm build
   ```

2. Start the bot:
   ```bash
   pnpm start
   ```

3. For development with linting:
   ```bash
   pnpm lint
   ```

### Architecture

#### Core Components

- **Main Entry Point** (`src/index.ts`): Initializes the Discord client, sets up event listeners, and starts the web server
- **Role Manager** (`src/modules/manageRoles.ts`): Core logic for detecting boost status and removing roles
- **Web Server** (`src/server/serve.ts`): Fastify-based HTTPS server for health monitoring
- **Error Handler** (`src/utils/errorHandler.ts`): Centralised error handling with Sentry integration and Discord webhook notifications
- **Log Handler** (`src/utils/logHandler.ts`): Winston-based logging with timestamps and colour coding

#### Bot Intents

The bot requires the following Discord gateway intents (src/index.ts:22):
- `Guilds`: Access to guild information
- `GuildMembers`: Access to member updates (privileged intent)

Note: The `GuildMembers` intent must be enabled in your bot's Discord Developer Portal settings.

#### Event Flow

1. Bot connects to Discord and fetches guild members (src/index.ts:25-39)
2. Bot listens for `guildMemberUpdate` events (src/index.ts:42-44)
3. On member update, `manageRoles` function checks boost status (src/modules/manageRoles.ts:13-26)
4. If member is not boosting, configured colour roles are removed
5. Errors are logged and sent to Sentry and debug webhook

#### Web Server

The Fastify server runs on port 3443 with HTTPS and provides:
- Health check endpoint at `/` (src/server/serve.ts:27-66)
- Simple HTML page with bot information and links
- Status notifications sent to debug webhook on startup

### Monitoring and Debugging

#### Sentry Integration

All errors are automatically captured and sent to Sentry (src/index.ts:9-17), providing:
- Stack trace rewriting for better debugging
- Full error context and stack traces
- 100% transaction sampling rate

#### Discord Webhooks

Debug webhooks are used for:
- Bot startup confirmation (src/index.ts:26-31)
- Member count logging (src/index.ts:35-39)
- Server startup notification (src/server/serve.ts:73-80)
- Error notifications with embeds (src/utils/errorHandler.ts:22-38)

#### Logging

Winston logger provides console output with:
- Timestamps in `YYYY-MM-DD HH:mm:ss` format
- Colour-coded log levels
- NPM-style log levels (silly, verbose, info, warn, error)

### Deployment Considerations

1. **Privileged Intents**: Ensure `GuildMembers` intent is enabled in Discord Developer Portal
2. **SSL Certificates**: Keep certificates up-to-date (consider using certbot for Let's Encrypt)
3. **Environment Variables**: Secure your `.env` file and never commit it to version control
4. **Port Access**: Ensure port 3443 is accessible for health monitoring
5. **Process Management**: Consider using PM2 or systemd for process management
6. **Single Guild**: Bot is designed for single-guild operation (src/index.ts:33)

## 3. Legal Documentation

This section is for expansions to our legal policies specific to the Application.

### Software License

This Application is licensed under the global software licence maintained by Naomi Carrigan. Full licence details can be found at: https://docs.nhcarrigan.com/#/license

Copyright is held by Naomi Carrigan.

### Privacy Considerations

The Application processes the following Discord data:
- **Guild member information**: Required for detecting boost status changes
- **Role information**: Required for managing booster-exclusive roles
- **Member update events**: Monitored to detect boost status changes

This data is processed in real-time and is not permanently stored by the Application outside of:
- Error logs sent to Sentry
- Debug messages sent to Discord webhooks
- Console logs from Winston logger

For full privacy policy details, see: PRIVACY.md

### Terms of Service

The Application operates as an automated moderation tool for Discord servers. Server administrators are responsible for:
- Configuring appropriate role IDs
- Informing server members about automated role management
- Ensuring compliance with Discord's Terms of Service

For full terms of service, see: TERMS.md

### Security Policy

Security vulnerabilities should be reported according to the guidelines in: SECURITY.md

## 4. Contributing Documentation

This section is for documentation related to contributing to the Application's codebase.

### Getting Started

Full contributing guidelines are available at: https://docs.nhcarrigan.com/#/contributing

### Development Setup

1. Fork and clone the repository
2. Install dependencies with `pnpm install`
3. Create a `.env` file from `sample.env`
4. Make your changes in a feature branch
5. Run linting with `pnpm lint` before committing
6. Build the project with `pnpm build` to ensure TypeScript compiles

### Code Style

The project uses:
- **ESLint**: `@nhcarrigan/eslint-config` (max 0 warnings)
- **Prettier**: `@nhcarrigan/prettier-config`
- **TypeScript**: `@nhcarrigan/typescript-config`

Run `pnpm lint` to check code style before submitting PRs.

### Project Structure

```
src/
├── index.ts                    # Main entry point
├── config/
│   └── roles.ts               # Role ID configuration
├── modules/
│   └── manageRoles.ts         # Core role management logic
├── server/
│   └── serve.ts               # Fastify web server
└── utils/
    ├── errorHandler.ts        # Centralised error handling
    └── logHandler.ts          # Winston logging configuration
```

### Testing

Currently, the project does not have automated tests (package.json:11). When contributing new features, consider:
- Manual testing with a test Discord server
- Verifying role removal works correctly
- Testing error handling paths
- Checking webhook notifications

### Submitting Changes

1. Ensure code passes linting: `pnpm lint`
2. Build successfully: `pnpm build`
3. Review the Code of Conduct: CODE_OF_CONDUCT.md
4. Submit a Pull Request with:
   - Clear description of changes
   - Rationale for the changes
   - Any testing performed

### Code of Conduct

All contributors must adhere to the Code of Conduct outlined in: CODE_OF_CONDUCT.md

### Reporting Issues

Bug reports and feature requests should be posted in the #bug-reports or #feature-requests forum channels on our Discord community.

### Contact

For questions or support:
- **Chat Server**: https://chat.nhcarrigan.com
- **Email**: contact@nhcarrigan.com
