# AeThex Unified Bot

## Overview

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.

---

## 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 |

### 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