discord-rpg-concept/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)
│   └── index.ts         # Bot entry point
├── web/                 # REST API server
│   └── src/routes/      # API route handlers
├── shared/              # Shared code between bot and web
│   ├── db/              # Database schema and Drizzle ORM
│   ├── lib/             # Utilities, config, logger, events
│   ├── modules/         # Domain services (economy, admin, quest)
│   └── config/          # Configuration files
├── 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)
  • inventory/: Item management commands
  • leveling/: XP and level tracking
  • quest/: Quest commands
  • user/: User profile commands
• 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 (web/)

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
• 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

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. Shared Core (shared/)

Shared code accessible by both bot and web applications.

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, trading
• admin/: Administrative actions (maintenance mode, cache clearing)
• quest/: Quest creation and tracking
• dashboard/: Dashboard statistics and real-time event bus
• leveling/: XP and leveling logic

Utilities (shared/lib/):

• config.ts: Application configuration management
• logger.ts: Structured logging system
• env.ts: Environment variable handling
• events.ts: Event bus for inter-module communication
• constants.ts: Application-wide constants

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