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+)
• MongoDB 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 SpellWare configuration (zero warnings policy)
3. Database: Prisma ORM with MongoDB
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