# 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

```bash
# 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`.