---
title: Pavelle
---

Pavelle (hereinafter the "Application") is a Discord bot that allows users to throw things (like cake) at their fellow server members in a fun, interactive game with scoring and leaderboards.

## 1. User Documentation

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

### Commands

The bot provides the following slash commands:

#### `/throw [target]`
- **Purpose**: Throw an item (based on server theme) at another user
- **Usage**: `/throw @username` or `/throw` (for random target)
- **Rate Limit**: 10 throws per hour per user (resets every hour)
- **Scoring System**:
  - **Counter Hit (-1 points)**: Target catches and throws back (10% chance)
  - **Miss (0 points)**: Throw fails to hit target (40% chance)
  - **Hit (+1 point)**: Successfully hits target (45% chance)
  - **Bonus Hit (+5 points)**: Exceptional throw with special effects (5% chance)

#### `/leaderboard`
- **Purpose**: Display server leaderboard showing top 10 players and your rank
- **Usage**: `/leaderboard`
- **Features**: Shows total points and ranking for all players

#### `/config [theme] [spoiler]`
- **Purpose**: Configure server settings (requires Manage Guild permission)
- **Parameters**:
  - `theme`: Visual theme for throws (currently supports "cake")
  - `spoiler`: Whether to hide result GIFs behind spoiler tags
- **Usage**: `/config theme:cake spoiler:true`

#### `/about`
- **Purpose**: Display information about the bot

### Gameplay Features

- **Hourly Reset**: Throw counts reset at the top of every hour
- **Interactive Results**: Each throw result includes themed messages, GIFs, and buttons
- **Persistent Scoring**: Points are tracked across sessions and contribute to server leaderboards
- **Guild-Specific**: Each server maintains its own leaderboard and configuration

## 2. Technical Documentation

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

### Prerequisites

- Node.js (version compatible with TypeScript 5.9.2)
- pnpm package manager (version 10.14.0+)
- PostgreSQL database (via Prisma ORM)
- Discord Bot Token
- 1Password CLI (for production secrets management)

### Installation

1. Clone the repository
2. Install dependencies: `pnpm install`
3. Set up database with Prisma: `pnpm run build` (includes `prisma generate`)
4. Configure environment variables (see Configuration section)

### Configuration

Required environment variables:
- `BOT_TOKEN`: Discord bot token
- Database connection string for Prisma

### Scripts

- `pnpm run build`: Generate Prisma client and compile TypeScript
- `pnpm run lint`: Run ESLint with zero warnings policy
- `pnpm run start`: Start production build with 1Password environment
- `pnpm test`: Currently returns success (no tests implemented)

### Architecture

**Core Components**:
- **Discord Client**: Handles Discord.js interactions with guild-only intent filtering
- **Prisma Database**: Manages user scores and server configurations
- **Caching System**: Hourly throw count cache to prevent database spam
- **Scheduled Jobs**: Automatic cache clearing every hour
- **Fastify Server**: Web server component for additional functionality

**Key Modules**:
- `processCommand.ts`: Routes slash commands to handlers
- `processButton.ts`: Handles interactive button responses
- `generateScore.ts`: Implements weighted random scoring system
- `checkEntitlement.ts`: Validates guild permissions/access
- `getThrowComponents.ts`: Builds Discord UI components for results

**Database Schema**:
- `users`: Stores per-server user scores (`serverId`, `userId`, `points`)
- `servers`: Stores per-server configuration (`serverId`, `theme`, `spoiler`)

### Security Features

- Guild-only operation (DM interactions blocked)
- Permission-based configuration (Manage Guild required)
- Input validation and type guards
- Comprehensive error handling with UUID tracking
- Rate limiting via hourly throw counts

## 3. Legal Documentation

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

### License
This software is licensed under Naomi's Public Licence as specified in the source code headers.

### Data Collection
The Application collects and stores:
- Discord user IDs and server IDs for scoring functionality
- Throw counts and point totals per user per server
- Server configuration preferences (themes, spoiler settings)

### Data Retention
- User scores persist indefinitely unless manually removed
- Throw count cache is cleared hourly
- No message content or personal information is stored

### Third-Party Services
The Application integrates with:
- Discord API for bot functionality
- Database service for persistent storage
- 1Password for secure credential management (production)

## 4. Contributing Documentation

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

### Development Setup

1. **Environment**: Node.js with TypeScript, pnpm package manager
2. **Code Standards**: ESLint with NHCarrigan configuration (zero warnings policy)
3. **Database**: Prisma ORM with PostgreSQL
4. **Framework**: Discord.js v14 with slash commands

### Code Style Guidelines

- **Licensing**: All files must include copyright header with Naomi's Public Licence
- **Comments**: Minimal commenting (code should be self-documenting)
- **TypeScript**: Strict typing with explicit interfaces
- **ESLint**: Zero warnings policy enforced in CI
- **Naming**: Follow existing conventions (camelCase, descriptive names)

### Architecture Patterns

- **Command Pattern**: Each slash command in separate file with common interface
- **Error Handling**: Centralised error handler with UUID tracking
- **Type Safety**: Comprehensive TypeScript interfaces and type guards
- **Separation of Concerns**: Clear module boundaries (commands, modules, utils, config)

### Adding New Features

1. **Themes**: Add new theme data to `config/themes.ts` with all message variants
2. **Commands**: Create new command file in `commands/` implementing `Command` interface
3. **Scoring**: Modify `generateScore.ts` for new scoring mechanics
4. **Database**: Update Prisma schema and run migrations as needed

### Testing

- Currently no test framework implemented
- Manual testing via Discord bot interactions required
- Lint checking enforced: `pnpm run lint`

### Deployment

- Production uses 1Password CLI for secure environment management
- Build process includes Prisma client generation
- TypeScript compilation to `prod/` directory
