AeThex-Bot-Master/replit.md

AeThex Unified Bot

Overview

The AeThex Unified Bot is a comprehensive, production-ready Discord bot powering the entire AeThex ecosystem. It provides enterprise-level security, cross-server federation, community engagement features, and multi-purpose server management—all unified into a single powerful instance.

Current Status

• Access: Open to all Discord servers (tiered feature access)
• Official Servers: 8 AeThex servers (Corporation, Main, Nexus, GameForge, LABS, DevOps, Foundation, Lone Star Studio)
• Commands: 76 fully implemented slash commands
• Database: Supabase (PostgreSQL) with 30+ tables
• Music: Dual Lavalink nodes for high-availability streaming
• Web Dashboard: Full admin interface on port 5000
• Federation: Cross-server protection network with trust levels and reputation scoring

---

Tiered Access Model

The bot is now publicly available for any Discord server to add. Features are organized into tiers:

Free Tier (All Servers)

All servers get immediate access to core features:

• XP & Leveling System
• Music Player (YouTube, Spotify, SoundCloud)
• Basic Moderation (warn, kick, ban, timeout)
• Achievements & Quests
• Welcome/Goodbye Messages
• Polls, Embeds, Announcements
• Daily Rewards & Shop System

Federation Tier (Verified Servers)

Servers can apply to join the Federation network for advanced protection:

• Cross-server ban synchronization
• Global reputation tracking
• Sentinel threat detection
• Trust level progression
• Cross-server role sync
• Server directory listing

How to Join: Use /federation membership apply to submit an application.

Premium Tier ($50/month)

Verified federation servers can upgrade for enhanced protection:

• Auto-kick/ban for ALL severity levels (not just critical)
• Featured server slots
• Priority support
• Advanced analytics

Official Tier

AeThex-owned servers have full access to all features automatically.

---

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

6. Music System

Full-featured music player using Lavalink (Kazagumo/Shoukaku).

Command	Description
/music play	Play a song or playlist (YouTube, Spotify, SoundCloud)
/music skip	Skip the current track
/music stop	Stop playback and clear queue
/music pause	Pause the current track
/music resume	Resume playback
/music queue	View the current queue
/music nowplaying	Show currently playing track with progress bar
/music volume	Adjust volume (0-100)
/music shuffle	Shuffle the queue
/music loop	Set loop mode (off/track/queue)

Features:

• Supports YouTube, Spotify, SoundCloud, Apple Music
• Automatic queue management
• Now playing embeds with thumbnails
• Progress bar display
• Automatic disconnect after queue ends

---

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

Federation System

Cross-server protection network that shares ban lists and reputation data.

Feature	Description
Global Bans	Shared ban list across all federation servers
Tiered Protection	Free (critical bans only) / Premium (all severity levels)
Server Directory	Public listing of verified federation servers
Applications	Treaty-based membership application system
Reputation	Cross-server talent scouting and reputation tracking
Featured Slots	Premium advertising spots for server promotion

Ban Severity Levels:

Level	Free Tier	Premium Tier
Low	Alert only	Auto-kick
Medium	Alert only	Auto-kick
High	Alert only	Auto-kick
Critical	Auto-ban	Auto-ban

Pricing:

• Free Tier: Basic protection (critical bans only)
• Premium Tier: $50/month - Full protection from all severity levels
• Featured Slot: $200/week - Cross-promotion across all federation servers

Dashboard: /federation - Web interface for managing federation membership

---

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

• 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