AeThex-Bot-Master/replit.md

# Bot Master

A centralized management dashboard for managing multiple Discord bots.

## Overview

Bot Master is a Flask-based web application that provides a central dashboard for monitoring and managing multiple Discord bots. It supports:

- **Bot Registry**: Store configurations for all your bots
- **Status Monitoring**: Real-time health checks for each bot
- **Statistics**: Track servers, commands, and uptime across all bots
- **CRUD Operations**: Add, edit, view, and delete bot configurations

## Tech Stack

- **Backend**: Python/Flask
- **Database**: PostgreSQL (via Flask-SQLAlchemy)
- **Frontend**: Jinja2 templates with custom CSS

## Project Structure

```
/
├── main.py              # Flask application entry point
├── templates/           # HTML templates
│   ├── base.html        # Base layout template
│   ├── dashboard.html   # Main dashboard view
│   ├── bots.html        # Bot list table view
│   ├── add_bot.html     # Add new bot form
│   ├── view_bot.html    # Bot details view
│   └── edit_bot.html    # Edit bot form
├── static/              # Static assets (currently empty)
└── attached_assets/     # Uploaded files and extracted bot examples
    ├── bot1/            # Example AeThex bot (basic)
    └── bot2/            # Example AeThex bot (extended with feed sync)
```

## Database Models

### Bot
- `id`: Primary key
- `name`: Bot name (required)
- `description`: Bot description
- `health_endpoint`: URL for health check API
- `admin_token`: Bearer token for authenticated endpoints
- `bot_type`: Type of bot (discord, telegram, slack, other)
- `status`: Current status (online, offline, unknown, timeout, error)
- `last_checked`: Timestamp of last health check
- `guild_count`, `command_count`, `uptime_seconds`: Stats from health endpoint
- `created_at`, `updated_at`: Timestamps

### BotLog
- Stores log entries per bot (for future logging features)

## API Endpoints

- `GET /` - Dashboard
- `GET /bots` - List all bots
- `GET /bots/add` - Add bot form
- `POST /bots/add` - Create new bot
- `GET /bots/<id>` - View bot details
- `GET /bots/<id>/edit` - Edit bot form
- `POST /bots/<id>/edit` - Update bot
- `POST /bots/<id>/delete` - Delete bot
- `POST /bots/<id>/check` - Check bot health

### API (JSON)
- `GET /api/bots` - List all bots as JSON
- `GET /api/bots/<id>/health` - Check specific bot health
- `POST /api/check-all` - Check all bots health

## Health Check Integration

Each bot should expose a health endpoint that returns JSON:
```json
{
  "status": "online",
  "guilds": 5,
  "commands": 12,
  "uptime": 3600
}
```

## Running the Application

The application runs on port 5000 using the Flask development server.

## Environment Variables

- `DATABASE_URL` - PostgreSQL connection string
- `FLASK_SECRET_KEY` - Secret key for session management (auto-generated if not set)

## Example Bots

The `attached_assets` folder contains two example AeThex Discord bots:
- **Bot 1**: Basic version with verify, profile, set-realm, unlink, verify-role commands
- **Bot 2**: Extended version with additional help, stats, leaderboard, post commands and feed sync

---

# Aethex Sentinel Bot

Enterprise-grade Discord bot for managing a federation of 5 servers.

## Overview

Aethex Sentinel is a TypeScript-based Discord bot built with the Sapphire framework. It provides:

- **Federation Sync**: Cross-server role synchronization
- **Sentinel Security**: Anti-nuke protection with heat-based threat detection
- **Commerce Module**: Ticket system with database persistence
- **Dashboard Updates**: Network status updates in voice channels

## Tech Stack

- **Runtime**: Node.js 20 + TypeScript
- **Framework**: @sapphire/framework
- **Database**: PostgreSQL (via Prisma ORM)
- **Health Endpoint**: HTTP server on port 8080

## Project Structure

```
sentinel-bot/
├── src/
│   ├── core/
│   │   ├── client.ts      - SapphireClient with Prisma
│   │   ├── config.ts      - Environment configuration
│   │   └── health.ts      - Health endpoint server
│   ├── modules/
│   │   ├── federation/FederationManager.ts  - Cross-server role sync
│   │   ├── security/HeatSystem.ts           - Anti-nuke protection
│   │   ├── commerce/TicketManager.ts        - Ticket system
│   │   └── dashboard/StatusUpdater.ts       - Network status updates
│   ├── listeners/
│   │   ├── ready.ts              - Bot ready handler
│   │   ├── guildMemberUpdate.ts  - Role sync listener
│   │   ├── auditLogCreate.ts     - Security monitor
│   │   └── interactionCreate.ts  - Button handler
│   ├── commands/
│   │   ├── federation.ts  - /federation command
│   │   ├── sentinel.ts    - /sentinel command
│   │   ├── ticket.ts      - /ticket command
│   │   └── status.ts      - /status command
│   └── index.ts           - Entry point
├── prisma/
│   └── schema.prisma      - Database models
├── package.json
├── tsconfig.json
└── .env.example
```

## Database Models (Prisma)

- **User**: Discord user profiles with federation membership
- **HeatEvent**: Security events for threat detection
- **Ticket**: Support tickets with transcripts
- **GuildConfig**: Per-guild configuration
- **RoleMapping**: Cross-server role sync mappings

## Commands

| Command | Description |
|---------|-------------|
| `/federation link` | Link a role across servers |
| `/federation unlink` | Remove a role mapping |
| `/federation list` | Show all role mappings |
| `/sentinel heat` | View heat level of a user |
| `/sentinel lockdown` | Enable/disable lockdown mode |
| `/sentinel config` | Configure security thresholds |
| `/ticket create` | Create a support ticket |
| `/ticket close` | Close a ticket with transcript |
| `/status` | View network status |

## Health Endpoint

The bot exposes a health endpoint compatible with Bot Master dashboard:

**GET /health** (port 8080)
```json
{
  "status": "online",
  "guilds": 5,
  "commands": 12,
  "uptime": 3600,
  "timestamp": "2025-12-07T12:00:00.000Z",
  "bot": {
    "tag": "Aethex Sentinel#1234",
    "id": "123456789"
  }
}
```

**GET /stats** (port 8080)
```json
{
  "guilds": [
    { "id": "...", "name": "...", "memberCount": 100 }
  ],
  "totalMembers": 500,
  "uptime": 3600
}
```

## Environment Variables

Required secrets (add in Replit Secrets tab):
- `DISCORD_TOKEN` - Discord bot token
- `DATABASE_URL` - PostgreSQL connection string

Optional configuration:
- `HUB_GUILD_ID` - Main hub server ID
- `FEDERATION_GUILD_IDS` - Comma-separated list of guild IDs
- `HEALTH_PORT` - Health server port (default: 8080)

## Running the Bot

```bash
cd sentinel-bot
npm install
npx prisma generate
npx prisma db push
npm run build
npm start
```

For development:
```bash
npm run dev
```

## Integration with Bot Master

Once the Sentinel bot is running, add it to Bot Master dashboard:
1. Go to Bot Master dashboard (port 5000)
2. Click "Add Bot"
3. Enter name: "Aethex Sentinel"
4. Enter health endpoint: `http://localhost:8080/health`
5. Select type: "discord"

The dashboard will automatically poll the health endpoint for status updates.