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 web dashboard 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/                 # React web dashboard
│   ├── src/             # React components and pages
│   │   ├── pages/       # Dashboard pages (Admin, Settings, Home)
│   │   ├── components/  # Reusable UI components
│   │   └── server.ts    # Web server with API endpoints
│   └── build.ts         # Vite build configuration
├── 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. Web Dashboard (web/)

A React 19 + Bun web application for bot administration and monitoring.

Key Pages:

• Home (/): Dashboard overview with live statistics
• Admin Overview (/admin/overview): Real-time bot metrics
• Admin Quests (/admin/quests): Quest management interface
• Settings (/settings/*): Configuration pages for:
  • General settings
  • Economy settings
  • Systems settings
  • Roles settings

Web Server Features:

• Built with Bun's native HTTP server
• WebSocket support for real-time updates
• REST API endpoints for dashboard data
• SPA fallback for client-side routing
• Bun dev server with hot module replacement

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 dashboard
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 dashboard with live statistics
   • Activity charts 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	React 19 + Bun
Database	PostgreSQL 17
ORM	Drizzle ORM
Styling	Tailwind CSS v4 + ShadCN/Radix UI
Validation	Zod
Containerization	Docker

Running the Application

# Database migrations
bun run migrate

# Production (Docker)
docker compose up

The bot and dashboard process run on port 3000 and are accessible at http://localhost:3000.