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)
│   └── 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

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