forked from syntaxbullet/aurorabot
feat: (docs) add main.md
This commit is contained in:
syntaxbullet
168
docs/main.md
Normal file
168
docs/main.md
Normal file
@@ -0,0 +1,168 @@
|
|||||||
|
# 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`.
|
||||||
Reference in New Issue
Block a user