AeThex-Labs/AeThex-Bot-Master
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Expand bot capabilities documentation with detailed feature overviews

Browse source 
Update replit.md to include expanded documentation on the bot's core capabilities, security, moderation, community features, and cross-platform integration, detailing systems like XP, Prestige, Achievements, Quests, Shop, Sentinel Anti-Nuke, and Auto-Moderation.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: aed2e46d-25bb-4b73-81a1-bb9e8437c261
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: 2d25d0df-0eaf-41d3-9b0a-f5dad78a437e
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/3bdfff67-975a-46ad-9845-fbb6b4a4c4b5/aed2e46d-25bb-4b73-81a1-bb9e8437c261/xfdSNeM
Replit-Helium-Checkpoint-Created: true
This commit is contained in:
sirpiglr 2025-12-09 03:52:17 +00:00
parent 0939d1d20a
commit 3691dc4b08
1 changed files with 318 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

355
replit.md
View file

@ -2,44 +2,325 @@
## Overview
The AeThex Unified Bot is a comprehensive Discord bot designed to integrate community features, enterprise-level security, and multi-purpose server management. It aims to unify various functionalities into a single, powerful instance for the AeThex ecosystem.
The AeThex Unified Bot is a comprehensive Discord bot designed to integrate community features, enterprise-level security, and multi-purpose server management. It unifies various functionalities into a single, powerful instance for the AeThex ecosystem across 5+ linked servers.
Key capabilities include:
- **Community Engagement**: User verification, profile linking, realm selection, leaderboards, community posts, leveling system, role panels, and giveaways.
- **Sentinel Security**: Anti-nuke protection with RAM-based heat tracking to safeguard servers.
- **Federation Sync**: Cross-server role synchronization across multiple realms.
- **Support & Moderation**: A ticket system for support, a full suite of moderation tools (warn, kick, ban, timeout), and auto-moderation for content filtering.
- **Cross-Platform Integration**: Seamless connection with AeThex.studio and AeThex.foundation platforms.
---
## Core Capabilities
### 1. Unified XP & Leveling System
A cross-platform leveling system that tracks XP globally across ALL servers.
| Feature | Description |
|---------|-------------|
| **Global XP** | XP earned in any server counts toward your unified profile |
| **XP Sources** | Messages, reactions, voice chat, daily claims, quest completions |
| **Leveling Formula** | `level = floor(sqrt(xp / base))` with configurable difficulty (easy/normal/hard) |
| **XP Cooldowns** | Configurable cooldown between XP gains (default: 60 seconds) |
| **Bonus Channels** | Server admins can set XP multipliers for specific channels |
| **Role Multipliers** | Certain roles can earn XP faster (e.g., boosters get 1.5x) |
### 2. Prestige System
Users who reach Level 50 can "prestige" to reset their XP for permanent bonuses.
| Prestige Level | Bonus |
|----------------|-------|
| Prestige 1 | +5% XP gain permanently |
| Prestige 2 | +10% XP gain permanently |
| Prestige 3+ | +5% per level (stacking) |
| Rewards | Unique badges, exclusive roles, bragging rights |
### 3. Achievement System
Custom server achievements with various triggers and rewards.
| Trigger Type | Description |
|--------------|-------------|
| `level` | Reach a specific level |
| `prestige` | Reach a prestige level |
| `xp` | Accumulate total XP |
| `messages` | Send X messages |
| `reactions` | Give/receive reactions |
| `voice_time` | Spend time in voice channels |
| `daily_streak` | Maintain daily claim streak |
| `commands_used` | Use bot commands |
**Rewards:** XP bonuses, special roles, hidden achievements for dedicated users.
### 4. Quest System
Daily and weekly challenges that reward XP.
| Quest Type | Duration | Examples |
|------------|----------|----------|
| Daily | 24 hours | "Send 10 messages", "React to 5 posts" |
| Weekly | 7 days | "Spend 60 minutes in voice", "Earn 500 XP" |
### 5. Shop System
Users can spend their XP on items configured by server admins.
| Item Types | Examples |
|------------|----------|
| Roles | Purchase exclusive roles |
| Badges | Cosmetic profile badges |
| Boosts | Temporary XP multipliers |
| Custom | Server-specific rewards |
---
## Security & Moderation
### Sentinel Anti-Nuke Protection
RAM-based heat tracking system that monitors for malicious activity.
| Protection | Trigger |
|------------|---------|
| Mass Ban Detection | Multiple bans in short timeframe |
| Mass Kick Detection | Multiple kicks in short timeframe |
| Role Deletion | Bulk role deletions |
| Channel Deletion | Bulk channel deletions |
**Response:** Automatic lockdown, admin alerts, action reversal.
### Auto-Moderation
Configurable content filtering with adjustable actions.
| Filter | Description | Actions |
|--------|-------------|---------|
| Links | Block unauthorized URLs | Warn, Delete, Timeout |
| Spam | Detect message spam | Warn, Delete, Timeout |
| Bad Words | Custom word blacklist | Warn, Delete, Timeout |
| Invites | Block Discord invites | Warn, Delete, Timeout |
| Mentions | Limit mass mentions | Warn, Delete, Timeout |
### Moderation Tools
| Command | Description |
|---------|-------------|
| `/warn` | Issue a warning (tracked in database) |
| `/kick` | Kick user from server |
| `/ban` | Ban user from server |
| `/timeout` | Temporarily mute user |
| `/modlog` | View moderation history |
| `/auditlog` | View server audit log |
---
## Community Features
### User Verification
Link Discord accounts to AeThex platform profiles.
| Command | Description |
|---------|-------------|
| `/verify` | Link your Discord to AeThex account |
| `/unlink` | Remove account link |
| `/profile` | View your unified profile |
| `/rank` | Check your current rank |
### Role Panels
Interactive button-based role selection.
| Feature | Description |
|---------|-------------|
| Self-assign roles | Users click buttons to get roles |
| Multiple panels | Create different panels for different role categories |
| Customizable | Set colors, descriptions, requirements |
### Giveaways
Automated giveaway system.
| Feature | Description |
|---------|-------------|
| Create | Set prize, duration, winner count |
| Requirements | Level requirements, role requirements |
| Auto-end | Automatically picks winners |
| Reroll | Re-pick winners if needed |
### Leaderboards
Multiple ranking categories.
| Category | Description |
|----------|-------------|
| All-Time XP | Global XP leaders |
| Weekly | Most XP earned this week (per server) |
| Monthly | Most XP earned this month (per server) |
| Posts | Most community posts |
| Likes | Most liked content |
### Welcome/Goodbye Messages
Rich embed messages for member join/leave.
| Feature | Description |
|---------|-------------|
| Welcome | Custom embed when users join |
| Goodbye | Custom embed when users leave |
| Variables | Username, server name, member count |
---
## Cross-Platform Integration
### Federation Sync
Cross-server role synchronization across linked guilds.
| Feature | Description |
|---------|-------------|
| Role Mapping | Map roles between servers |
| Auto-sync | Roles update automatically |
| Realm Selection | Users choose their "home" realm |
### Platform Links
| Platform | Integration |
|----------|-------------|
| AeThex.studio | View user profiles, portfolios |
| AeThex.foundation | View contributions, donations |
---
## Administrative Features
### Web Dashboard
Browser-based admin interface at `/dashboard`.
| Page | Features |
|------|----------|
| **XP Settings** | Configure XP rates, cooldowns, multipliers |
| **Manage Quests** | Create/edit/delete quests |
| **Manage Achievements** | Configure achievement triggers and rewards |
| **Manage Shop** | Add/edit shop items and pricing |
### Server Configuration
| Command | Description |
|---------|-------------|
| `/config` | View/edit server settings |
| `/xp-settings` | Configure XP system |
| `/level-roles` | Set auto-assign roles at levels |
| `/automod` | Configure auto-moderation |
| `/admin` | Administrative commands |
### Scheduled Messages
Timed announcements with embed support.
| Feature | Description |
|---------|-------------|
| Schedule | Set date/time for message |
| Embeds | Rich embed formatting |
| Recurring | Daily/weekly/monthly options |
---
## All Commands (44 Total)
### Community & Leveling
| Command | Description |
|---------|-------------|
| `/profile` | View your unified profile |
| `/rank` | Check your current rank and level |
| `/daily` | Claim daily XP reward |
| `/leaderboard` | View server/global rankings |
| `/prestige` | Reset at Level 50 for bonuses |
| `/achievements` | View available achievements |
| `/quests` | View and track quests |
| `/shop` | Browse and purchase items |
| `/stats` | View detailed statistics |
| `/badges` | View your earned badges |
### Verification & Linking
| Command | Description |
|---------|-------------|
| `/verify` | Link Discord to AeThex account |
| `/unlink` | Remove account link |
| `/verify-role` | Check verification status |
| `/set-realm` | Choose your home realm |
### Moderation
| Command | Description |
|---------|-------------|
| `/warn` | Issue a warning |
| `/kick` | Kick a user |
| `/ban` | Ban a user |
| `/timeout` | Timeout a user |
| `/modlog` | View moderation history |
| `/auditlog` | View audit log |
### Utility
| Command | Description |
|---------|-------------|
| `/help` | View all commands |
| `/serverinfo` | Server information |
| `/userinfo` | User information |
| `/avatar` | View user's avatar |
| `/poll` | Create a poll |
| `/embed` | Create custom embeds |
| `/announce` | Make announcements |
| `/status` | Bot status and uptime |
### Admin
| Command | Description |
|---------|-------------|
| `/config` | Server configuration |
| `/xp-settings` | XP system settings |
| `/level-roles` | Level-up role rewards |
| `/automod` | Auto-moderation settings |
| `/rolepanel` | Create role panels |
| `/giveaway` | Manage giveaways |
| `/schedule` | Schedule messages |
| `/admin` | Admin utilities |
| `/quests-manage` | Manage quests |
| `/shop-manage` | Manage shop items |
| `/refresh-roles` | Sync federation roles |
### Cross-Platform
| Command | Description |
|---------|-------------|
| `/studio` | View AeThex.studio profile |
| `/foundation` | View AeThex.foundation profile |
| `/federation` | Federation sync settings |
| `/post` | Create community post |
---
## Technical Architecture
### Stack
- **Runtime:** Node.js 20
- **Framework:** discord.js v14
- **Database:** Supabase (PostgreSQL)
- **Web Server:** Express.js
### Database Tables
| Table | Purpose |
|-------|---------|
| `user_profiles` | Global user data, XP, prestige |
| `user_stats` | Per-server activity statistics |
| `discord_links` | Discord ↔ AeThex account links |
| `server_config` | Per-server bot configuration |
| `achievements` | Achievement definitions |
| `user_achievements` | Earned achievements |
| `quests` | Quest definitions |
| `shop_items` | Shop item catalog |
| `warnings` | Moderation warnings |
| `mod_actions` | Moderation action log |
| `giveaways` | Active giveaways |
| `role_panels` | Role panel configurations |
| `level_roles` | Level-up role rewards |
| `automod_config` | Auto-moderation settings |
| `periodic_xp` | Weekly/monthly XP tracking |
| `scheduled_messages` | Scheduled announcements |
### Ports
| Port | Service |
|------|---------|
| 5000 | Web Dashboard |
| 8080 | Health Check / API |
---
## User Preferences
I prefer iterative development and receiving explanations that focus on the "why" behind changes, not just the "what". Please provide clear, step-by-step instructions for any complex tasks. I also appreciate it when you anticipate potential issues and suggest solutions proactively.
## System Architecture
The bot is built on **Node.js 20** using the **discord.js v14** framework. It follows a modular design with commands and event listeners separated into distinct directories.
**Key Architectural Decisions:**
- **Modular Command and Event Handling**: Commands are organized by function, and events are handled by dedicated listeners, promoting maintainability and scalability.
- **Unified XP System**: A cross-platform leveling system tracks XP from Discord messages, reactions, voice chat, daily claims, and AeThex platform activity. XP is unified across all platforms and stored in a single user profile.
- Leveling formula: `level = floor(sqrt(xp / base))`, with configurable base difficulty.
- **Prestige System**: Users can reset XP at Level 50 for permanent bonuses and rewards, including XP multipliers and unique badges.
- **Sentinel Security Module**: Implements RAM-based heat tracking for anti-nuke protection, monitoring for mass bans, kicks, role deletions, and channel deletions.
- **Federation Sync**: Manages cross-server role synchronization to ensure consistent access and permissions across linked guilds.
- **Interactive UI**: Utilizes Discord's button interactions for features like role panels and modals for custom embed creation.
- **Web Dashboard**: A `dashboard.html` file in the `public/` directory is available for potential web-based interactions or monitoring.
**Feature Specifications:**
- **40 Commands**: Covering community, leveling, moderation, utility, admin, cross-platform, and security functions.
- **Rich Embeds**: Used extensively for welcome/goodbye messages, user profiles, server info, and announcements.
- **Configurable Auto-moderation**: Settings for link, spam, badword, invite, and mention filtering with adjustable actions.
- **Scheduled Messages**: Allows scheduling timed announcements with support for embeds.
- **Giveaway System**: Automated creation, management, and rerolling of giveaways.
- **Achievement System**: Custom server achievements with various triggers (level, prestige, XP, messages, reactions, voice time, daily streak, commands used), XP rewards, role rewards, and hidden achievements.
## External Dependencies
- **Database**: Supabase (used for `server_config`, `warnings`, `mod_actions`, `level_roles`, `role_panels`, `giveaways`, `scheduled_messages`, `automod_config`, `user_profiles`, `achievements`, `user_achievements`, and `user_stats` tables).
- **Discord API**: `discord.js v14` for interacting with the Discord platform.
- **AeThex.studio**: Integration for viewing user profiles.
- **AeThex.foundation**: Integration for viewing user contributions.
- Iterative development with clear explanations
- Focus on the "why" behind changes
- Proactive issue anticipation
- Blue theme (hsl(220, 100%, 65%))
- Fira Code / Source Code Pro fonts