feat: (docs) add main.md

2026-01-16 13:34:35 +01:00
parent 47ce0f12e6
commit d243a11bd3
1 changed files with 168 additions and 0 deletions
--- a/docs/main.md
+++ 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`.