diff --git a/replit.md b/replit.md index 263ebd8..6a8a703 100644 --- a/replit.md +++ b/replit.md @@ -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. \ No newline at end of file +- 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