discord-rpg-concept/README.md

Aurora

A comprehensive, feature-rich Discord RPG bot built with modern technologies.

Aurora is a powerful Discord bot designed to facilitate RPG-like elements within a Discord server. It features a robust economy, class system, inventory management, quests, and more, all built on top of a high-performance stack using Bun and Drizzle ORM.

New in v1.0: Aurora now includes a fully integrated Web Dashboard for managing the bot, viewing statistics, and configuring settings, running alongside the bot in a single process.

✨ Features

Discord Bot

• Class System: Users can join different classes.
• Economy: Complete economy system with balance, transactions, and daily rewards.
• Inventory & Items: Sophisticated item system with rarities, types (Material, Consumable, etc.), and inventory management.
• Leveling: XP-based leveling system to track user activity and progress.
• Quests: Quest system with requirements and rewards.
• Trading: Secure trading system between users.
• Lootdrops: Random loot drops in channels to engage users.
• Admin Tools: Administrative commands for server management.

Web Dashboard

• Live Analytics: View real-time activity charts (commands, transactions).
• Configuration Management: Update bot settings without restarting.
• Database Inspection: Integrated Drizzle Studio access.
• State Monitoring: View internal bot state (Lootdrops, etc.).

🏗️ Architecture

Aurora uses a Single Process Monolith architecture to maximize performance and simplify resource sharing.

• Unified Runtime: Both the Discord Client and the Web Dashboard run within the same Bun process.
• Shared State: This allows the Dashboard to access live bot memory (caches, gateways) directly without complex inter-process communication (IPC).
• Simplified Deployment: You only need to deploy a single Docker container.

🛠️ Tech Stack

• Runtime: Bun
• Bot Framework: Discord.js
• Web Framework: React 19 + Vite (served via Bun)
• Styling: Tailwind CSS v4 + Radix UI
• Database: PostgreSQL
• ORM: Drizzle ORM
• Validation: Zod
• Containerization: Docker

🚀 Getting Started

Prerequisites

• Bun (latest version)
• Docker & Docker Compose

Installation

1. Clone the repository

   git clone <repository-url>
   cd aurora
   

2. Install dependencies

   bun install
   

3. Environment Setup Copy the example environment file and configure it:

   cp .env.example .env
   

   Edit .env with your Discord bot token, Client ID, and database credentials.

   Note

   : The DATABASE_URL in .env.example is pre-configured for Docker.

4. Start the Database Run the database service using Docker Compose:

   docker compose up -d db
   

5. Run Migrations

   bun run migrate
   

   OR

   bun run db:push
   

Running the Bot & Dashboard

Development Mode (with hot reload):

bun run dev

• Bot: Online in Discord
• Dashboard: http://localhost:3000

Production Mode: Build and run with Docker (recommended):

docker compose up -d app

🔐 Accessing Production Services (SSH Tunnel)

For security, the Production Database and Dashboard are not exposed to the public internet by default. They are only accessible via localhost on the server.

To access them from your local machine, use the included SSH tunnel script.

1. Add your VPS details to your local .env file:

   VPS_USER=root
   VPS_HOST=123.45.67.89
   

2. Run the remote connection script:

   bun run remote
   

This will establish secure tunnels for:

• Dashboard: http://localhost:3000
• Drizzle Studio: http://localhost:4983

📜 Scripts

• bun run dev: Start the bot and dashboard in watch mode.
• bun run remote: Open SSH tunnel to production services.
• bun run generate: Generate Drizzle migrations.
• bun run migrate: Apply migrations (via Docker).
• bun run db:studio: Open Drizzle Studio to inspect the database.
• bun test: Run tests.

📂 Project Structure

├── bot             # Discord Bot logic & entry point
├── web             # React Web Dashboard (Frontend + Server)
├── shared          # Shared code (Database, Config, Types)
├── drizzle         # Drizzle migration files
├── scripts         # Utility scripts
├── docker-compose.yml
└── package.json

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.