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

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