---
title: Umbrelle
---

Umbrelle (hereinafter the "Application") is a Discord bot that allows server administrators to configure honeypot channels to automatically detect and soft-ban compromised accounts. When an account posts in a designated honeypot channel, the bot will temporarily ban the user to remove their message history and immediately unban them, allowing them to return once they've recovered their account.

## 1. User Documentation

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

### Getting Started

1. **Adding Umbrelle to Your Server**
   - Use the Discord OAuth2 authorisation link: https://discord.com/oauth2/authorise?client_id=1412945347134881862
   - Ensure you have "Manage Server" permissions to add bots

2. **Setting Up a Honeypot Channel**
   - Use the `/honeypot` command followed by the channel you want to designate as a honeypot
   - Only users with "Manage Guild" permissions can configure honeypot channels
   - Example: `/honeypot channel:#suspicious-activity`

3. **How It Works**
   - When any user (excluding bots and system messages) posts in the configured honeypot channel, they will be automatically soft-banned
   - Soft-ban process:
     - User receives a DM explaining the situation
     - User is banned to remove message history (24 hours of messages)
     - User is immediately unbanned and can rejoin when ready
   - Only accounts that are "bannable" (not server owners, higher role hierarchy) will be affected

### Available Commands

- `/about` - Display information about Umbrelle and links to support resources
- `/honeypot <channel>` - Configure a honeypot channel (requires Manage Guild permission)

### Support and Help

If you need assistance:
- Join the support Discord server: https://chat.nhcarrigan.com
- Visit the documentation: https://docs.nhcarrigan.com/
- View source code: https://git.nhcarrigan.com/NHCarrigan/umbrelle

## 2. Technical Documentation

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

### Architecture Overview

Umbrelle is built with:
- **Discord.js v14** - Discord API interaction
- **TypeScript** - Type-safe development
- **Prisma** - Database ORM
- **MongoDB** - Data persistence
- **Fastify** - Web server for health monitoring
- **1Password CLI** - Secure environment variable management

### System Requirements

- Node.js (compatible with the version specified in package.json)
- MongoDB database
- Discord Bot Token
- 1Password CLI (for production deployment)

### Project Structure

```
src/
├── components/        # Discord UI components
│   └── about.ts      # About command interface
├── events/           # Discord event handlers
│   ├── handleInteraction.ts  # Slash command processing
│   ├── handleMessage.ts      # Message event handling
│   └── handleReady.ts        # Bot initialization
├── interfaces/       # TypeScript type definitions
│   └── umbrelle.ts   # Core application interface
├── server/           # Web server implementation
│   └── serve.ts      # Health monitoring server
├── utils/           # Utility functions
│   └── logger.ts    # Logging implementation
└── index.ts         # Application entry point
```

### Database Schema

The application uses a simple MongoDB schema with Prisma:

```prisma
model Honeypots {
  id        String @id @default(auto()) @map("_id") @db.ObjectId
  serverId  String @unique
  channelId String @unique
}
```

### Environment Variables

Required environment variables:
- `BOT_TOKEN` - Discord bot token
- `MONGO_URI` - MongoDB connection string

### Build and Deployment

1. **Development Setup**
   ```bash
   npm install
   npm run build
   ```

2. **Production Deployment**
   ```bash
   npm run start  # Uses 1Password CLI for environment management
   ```

3. **Available Scripts**
   - `build` - Generate Prisma client and compile TypeScript
   - `lint` - Run ESLint with zero warnings tolerance
   - `start` - Production start with 1Password environment loading
   - `test` - Placeholder test command

### Security Considerations

- Bot permissions are limited to Guild and Guild Messages intents
- Only users with Manage Guild permissions can configure honeypots
- Soft-ban mechanism preserves user ability to rejoin
- No sensitive data logging or exposure
- Follows Discord's best practices for bot development

## 3. Legal Documentation

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

### License

This application is licensed under Naomi's Public Licence. The full licence text can be found in the LICENSE.md file in the repository.

### Copyright

Copyright held by Naomi Carrigan (NHCarrigan).

### Data Handling

- Umbrelle stores minimal data: server IDs and channel IDs for honeypot configuration
- No user messages, personal information, or sensitive data is stored
- Database records are only used for bot functionality
- Users can request removal of their server's data by removing the bot from their server

### Terms of Service

Users should refer to TERMS.md for detailed terms of service.

### Privacy Policy

Users should refer to PRIVACY.md for detailed privacy policy information.

### Security Policy

Security concerns 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.

### Development Environment

1. **Prerequisites**
   - Node.js and npm/pnpm
   - MongoDB instance (local or cloud)
   - Discord application with bot token
   - Git for version control

2. **Setup Process**
   ```bash
   git clone <repository-url>
   cd umbrelle
   pnpm install
   # Configure environment variables
   pnpm run build
   ```

3. **Code Style**
   - ESLint configuration enforces code standards
   - Maximum warnings: 0 (strict enforcement)
   - TypeScript strict mode enabled
   - Follow existing patterns in the codebase

### Contribution Guidelines

Please refer to CONTRIBUTING.md for detailed contribution guidelines including:
- Code of conduct (CODE_OF_CONDUCT.md)
- Pull request process
- Issue reporting
- Development workflow

### Code Quality Standards

- All code must pass ESLint validation with zero warnings
- TypeScript strict mode compliance required
- Proper error handling for all async operations
- Comprehensive JSDoc comments for public functions
- Follow existing architectural patterns

### Testing

Currently, the project has placeholder tests. Contributors are welcome to:
- Implement comprehensive test coverage
- Add unit tests for core functionality
- Create integration tests for Discord interactions
- Establish CI/CD testing pipeline

### Contact and Support

For development questions and support:
- Join the Discord community: https://chat.nhcarrigan.com
- Email: contact@nhcarrigan.com
- Review existing discussions in the Discord forum channels (#bug-reports or #feature-requests)
