From d243a11bd3a0b3ab6a5c6e3c15c003cdec6718b8 Mon Sep 17 00:00:00 2001 From: syntaxbullet Date: Fri, 16 Jan 2026 13:34:35 +0100 Subject: [PATCH] feat: (docs) add main.md --- docs/main.md | 168 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 docs/main.md diff --git a/docs/main.md b/docs/main.md new file mode 100644 index 0000000..d702d54 --- /dev/null +++ b/docs/main.md @@ -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`.