docs/src/content/docs/projects/boost-monitor.md

title

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 color 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 color roles)

Key Features

• Automated Role Removal: No manual intervention needed when members stop boosting
• Configurable Roles: Server-specific booster and color 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:

   git clone https://github.com/nhcarrigan/oogie-woogie-boostie-woostie.git
   cd oogie-woogie-boostie-woostie
   

2. Install dependencies:

   pnpm install
   

3. Configure environment variables by creating a .env file:

   cp sample.env .env
   

4. Edit .env with your configuration:

   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:

export const colourRoles = [
  "883281643098484736", // Red role
  "883283836887261204", // Blue role
  // Add your color 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:

   pnpm build
   

2. Start the bot:

   pnpm start
   

3. For development with linting:

   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): Centralized error handling with Sentry integration and Discord webhook notifications
• Log Handler (src/utils/logHandler.ts): Winston-based logging with timestamps and color 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 color 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
• Color-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 license maintained by Naomi Carrigan. Full license 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        # Centralized 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 can be submitted at: https://github.com/nhcarrigan/oogie-woogie-boostie-woostie/issues

Contact

For questions or support:

• Chat Server: http://chat.nhcarrigan.com
• Email: contact@nhcarrigan.com