aurorabot/docs/main.md

Aurora - Discord RPG Bot

A comprehensive, feature-rich Discord RPG bot built with modern technologies using a monorepo architecture.

Architecture Overview

Aurora uses a Single Process Monolith architecture that runs both the Discord bot and REST API in the same Bun process. This design maximizes performance by eliminating inter-process communication overhead and simplifies deployment to a single Docker container.

Monorepo Structure

aurora-bot-discord/
├── bot/                 # Discord bot implementation
│   ├── commands/        # Slash command implementations
│   ├── events/          # Discord event handlers
│   ├── lib/             # Bot core logic (BotClient, utilities)
│   ├── modules/         # Feature modules (views, interactions per domain)
│   ├── graphics/        # Canvas-based image generation
│   └── index.ts         # Bot entry point
├── api/                 # REST API server
│   └── src/routes/      # API route handlers
├── shared/              # Shared code between bot and API
│   ├── db/              # Database schema and Drizzle ORM
│   ├── lib/             # Utilities, config, errors, logger, events
│   └── modules/         # Domain services (economy, admin, inventory, quest, etc.)
├── panel/               # React admin dashboard (Vite + Tailwind)
├── scripts/             # Helper scripts
├── docker-compose.yml   # Docker services (app, db)
└── package.json         # Root package manifest

Main Application Parts

1. Discord Bot (bot/)

The bot is built with Discord.js v14 and handles all Discord-related functionality.

Core Components:

• BotClient (bot/lib/BotClient.ts): Central client that manages commands, events, and Discord interactions
• Commands (bot/commands/): Slash command implementations organized by category:
  • admin/: Server management commands (config, prune, warnings, notes)
  • economy/: Economy commands (balance, daily, pay, trade, trivia)
  • feedback/: Feedback commands
  • inventory/: Item management commands
  • leveling/: XP and level tracking
  • quest/: Quest commands
  • user/: User profile commands
• Modules (bot/modules/): Feature modules with views and interaction handlers per domain (admin, economy, inventory, moderation, trade, trivia, etc.)
• Graphics (bot/graphics/): Canvas-based image generation (lootdrops, student IDs)
• Events (bot/events/): Discord event handlers:
  • interactionCreate.ts: Command interactions
  • messageCreate.ts: Message processing
  • ready.ts: Bot ready events
  • guildMemberAdd.ts: New member handling

2. REST API (api/)

A headless REST API built with Bun's native HTTP server for bot administration and data access.

Key Endpoints:

• Stats (/api/stats): Real-time bot metrics and statistics
• Settings (/api/settings): Configuration management endpoints
• Guild Settings (/api/guild-settings): Per-guild configuration
• Users (/api/users): User data and profiles
• Items (/api/items): Item catalog and management
• Quests (/api/quests): Quest data and progress
• Economy (/api/transactions): Economy and transaction data
• Moderation (/api/moderation): Moderation case data
• Classes (/api/classes): RPG class data
• Lootdrops (/api/lootdrops): Lootdrop data
• Health (/api/health): Health check endpoint

API Features:

• Built with Bun's native HTTP server
• WebSocket support for real-time updates (/ws)
• REST API endpoints for all bot data
• Real-time event streaming via WebSocket
• Zod validation for all requests

3. Admin Panel (panel/)

A React-based admin dashboard built with Vite and Tailwind CSS for managing the bot through a web interface.

4. Shared Core (shared/)

Shared code accessible by both the bot and API.

Database Layer (shared/db/):

• schema.ts: Drizzle ORM schema definitions for:
  • users: User profiles with economy data
  • items: Item catalog with rarities and types
  • inventory: User item holdings
  • transactions: Economy transaction history
  • classes: RPG class system
  • moderationCases: Moderation logs
  • quests: Quest definitions

Modules (shared/modules/):

• economy/: Economy service, lootdrops, daily rewards
• admin/: Administrative actions (maintenance mode, cache clearing)
• inventory/: Inventory management
• items/: Item catalog and management
• trade/: Trading system
• trivia/: Trivia game logic
• quest/: Quest creation and tracking
• class/: RPG class system
• leveling/: XP and leveling logic
• moderation/: Moderation case management
• user/: User profile management
• dashboard/: Dashboard statistics and real-time event bus
• guild-settings/: Per-guild configuration
• game-settings/: Game-wide settings
• feature-flags/: Feature flag management
• system/: System-level utilities

Utilities (shared/lib/):

• config.ts: Application configuration management
• logger.ts: Structured logging system
• env.ts: Environment variable handling
• errors.ts: Error classes (UserError, SystemError)
• events.ts: Event bus for inter-module communication
• eventWiring.ts: Event bus wiring
• constants.ts: Application-wide constants
• types.ts: Shared TypeScript types
• utils.ts: General utility functions
• rarity.ts: Item rarity definitions
• assets.ts: Asset path utilities

Main Use-Cases

For Discord Users

1. Class System: Users can join different RPG classes with unique roles
2. Economy:
   • View balance and net worth
   • Earn currency through daily rewards, trivia, and lootdrops
   • Send payments to other users
3. Trading: Secure trading system between users
4. Inventory Management: Collect, use, and trade items with rarities
5. Leveling: XP-based progression system tied to activity
6. Quests: Complete quests for rewards
7. Lootdrops: Random currency drops in text channels

For Server Administrators

1. Bot Configuration: Adjust economy rates, enable/disable features via API
2. Moderation Tools:
   • Warn, note, and track moderation cases
   • Mass prune inactive members
   • Role management
3. Quest Management: Create and manage server-specific quests
4. Monitoring:
   • Real-time statistics via REST API
   • Activity data and event logs
   • Economy leaderboards

For Developers

1. Single Process Architecture: Easy debugging with unified runtime
2. Type Safety: Full TypeScript across all modules
3. Testing: Bun test framework with unit tests for core services
4. Docker Support: Production-ready containerization
5. Remote Access: SSH tunneling scripts for production debugging

Technology Stack

Layer	Technology
Runtime	Bun 1.0+
Bot Framework	Discord.js 14.x
Web Framework	Bun HTTP Server (REST API)
Database	PostgreSQL 17
ORM	Drizzle ORM
Admin Panel	React + Vite + Tailwind CSS
UI	Discord embeds and components
Validation	Zod
Containerization	Docker

Running the Application

# Database migrations
bun run migrate

# Production (Docker)
docker compose up

The bot and API server run on port 3000 and are accessible at http://localhost:3000.