GizmoBot - Advanced Discord Bot Platform

A fully-featured, self-hostable Discord bot platform with real-time web dashboard, advanced plugin architecture, and comprehensive admin tools.

Quick Start

One command deployment:

curl -sSL https://raw.githubusercontent.com/maddi/gizmobot/master/install.sh | bash -s -- latest gizmobot auto-start

Then visit http://localhost:3000 to complete setup with your Discord bot token!

Alternative - Manual deployment:

git clone https://github.com/maddi/gizmobot.git
cd gizmobot
./install.sh
./gizmobot.sh start

Features

Discord Bot

• Enhanced Plugin Architecture: Multi-file plugins with per-guild database namespaces
• Multi-Server Support: Independent configuration per Discord server
• Analytics Tracking: Automatic message, voice, and event tracking
• Birthday Plugin: Automated birthday announcements with custom messages
• React Roles Plugin: Self-assignable roles via message reactions
• Auto Roles Plugin: Automatic role assignment on member join with welcome DMs
• Permission System: 5-level permission hierarchy (User → Supreme Owner)
• Event Logging: Comprehensive logging of all server events
• AI Integration: Google Gemini support for AI commands

API Features

• Discord OAuth 2.0: Secure authentication with JWT tokens
• Metrics Endpoints: Access server analytics and statistics
• Chart Exports: Generate Discord-themed PNG charts for metrics
• Plugin Management: Enable/disable and configure plugins per server
• Admin Dashboard: Supreme owner endpoints for global bot management
• Interactive Docs: Auto-generated Swagger UI and ReDoc
• Docker Ready: Containerized deployment with docker-compose

Analytics Capabilities

• Message Tracking: Total messages, edits, deletes with channel breakdown
• Voice Tracking: Session duration, total time, top voice users
• User Metrics: Per-user activity across messages and voice
• Timeline Charts: Daily message and voice activity visualizations
• Top Users: Rankings for most active chatters and voice users
• Export Options: Download metrics as PNG images

Architecture

GizmoBot is built with a modern, scalable architecture:

┌─────────────────────────────────────────────────┐
│              Docker Compose                     │
├──────────┬──────────┬──────────┬────────────────┤
│ Discord  │ FastAPI  │  React   │    MongoDB     │
│   Bot    │   API    │ Frontend │   Database     │
└──────────┴──────────┴──────────┴────────────────┘

Quick Start

Prerequisites

• Python 3.12+
• MongoDB 7+
• Discord Bot Token
• Docker & Docker Compose (optional, recommended)

Installation

Option 1: Docker (Recommended)

1. Clone the repository:

git clone https://github.com/MaddiFurr/YotelResortBot.git
cd YotelResortBot

2. Copy and configure environment variables:

cp .env.example .env
# Edit .env and add your configuration

3. Start the services:

docker-compose up -d

Option 2: Manual Installation

1. Clone and setup:

git clone https://github.com/MaddiFurr/YotelResortBot.git
cd YotelResortBot
chmod +x scripts/setup.sh
./scripts/setup.sh

2. Configure your environment:

# Edit .env with your configuration
nano .env

3. Run the bot:

python bot/__main__.py

Configuration

Required Environment Variables

## Configuration

### Database-First Approach
All configuration is handled through the web interface during first-run setup:

- **Discord Bot Token**: Validated and stored securely in database
- **Supreme Owner**: Your Discord user ID for admin access
- **Log Level**: DEBUG, INFO, WARNING, ERROR
- **Command Prefix**: Default text command prefix
- **Analytics Settings**: Enable/disable activity tracking
- **Data Retention**: How long to keep analytics (1-365 days)
- **Plugin Settings**: Per-guild plugin configuration

### Optional Environment Variables
Only needed for advanced deployments:
```bash
# MongoDB (auto-discovered if not set)
MONGODB_URI=mongodb://localhost:27017

# API settings (secure defaults used if not set)
API_HOST=0.0.0.0
API_PORT=8000

# Discord OAuth for dashboard (optional)
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret

See `.env.example` for all available configuration options.

##  Plugin System

### Creating a New Plugin

1. Create a directory in `bot/plugins/your_plugin/`
2. Create `plugin.py` that extends `BasePlugin`
3. Implement required methods and properties
4. Plugin will be auto-discovered on bot restart

Example plugin structure:
```python
from bot.plugins.base import BasePlugin
from discord import app_commands

class MyPlugin(BasePlugin):
    @property
    def name(self) -> str:
        return "my_plugin"
    
    @property
    def display_name(self) -> str:
        return "My Awesome Plugin"
    
    @property
    def description(self) -> str:
        return "Does something awesome!"
    
    @property
    def settings_schema(self) -> dict:
        return {
            "channel_id": {
                "type": "channel",
                "label": "Target Channel",
                "required": True
            }
        }
    
    def get_commands(self):
        @app_commands.command(name="mycommand")
        async def my_command(interaction):
            await interaction.response.send_message("Hello!")
        
        return [my_command]

Dashboard Features

For Server Admins

• Plugin Management: Enable/disable plugins, configure settings
• Analytics Dashboard: View server metrics and trends
• User Management: See detailed user information and activity
• Log Viewer: Browse server events and moderation actions
• Server Settings: Configure bot behavior per server

For Supreme Owner

• Bot Console: View logs and monitor bot status
• Plugin Reload: Hot-reload plugins without restart
• Global Management: Access all servers and configurations
• Security Settings: Manage API keys and tokens

Available Plugins

Birthday Plugin

• Set birthdays with /birthday
• Automated announcements
• Customizable messages
• Optional age display

More plugins coming soon!

• Auto Roles
• Reaction Roles
• Moderation Tools
• Fun Commands
• And many more...

Development

Project Structure

GizmoBot/
├── bot/                    # Discord bot
│   ├── core/              # Core functionality
│   ├── plugins/           # Plugin modules
│   ├── models/            # Database models
│   └── services/          # Shared services
├── api/                   # FastAPI backend (coming soon)
├── frontend/              # React dashboard (coming soon)
├── docker/                # Docker configurations
└── scripts/               # Utility scripts

Adding Features

1. Create a new plugin in bot/plugins/
2. Implement BasePlugin interface
3. Define settings schema for dashboard
4. Register commands and event listeners
5. Test and deploy

Database Models

• guilds: Server configurations and plugin settings
• users: User data across servers
• messages: Message tracking for analytics
• voice_sessions: Voice activity tracking
• logs: Event and moderation logs
• metrics_aggregated: Pre-computed analytics

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is proprietary software. All rights reserved.

Made with Love

GizmoBot is crafted with care for the furry community and beyond. Playful, professional, and powerful.

Support

For support, feature requests, or bug reports, please open an issue on GitHub or contact the maintainer.

---

Maintainer: Maddi (her@maddi.wtf)
Repository: https://github.com/MaddiFurr/YotelResortBot that I wrote to accomplish various tasks I needed or wanted on discord to save me time and effort.

This was build so that I could test different functionality and features to impliment in other areas as well.

Environment Setup

1. Setup a virtual environment py -3.12 -m venv

2. Activate your virtual invironment in your code editor (VS Code makes this easy btw so I highly suggest using that)

(Windows) ./Scripts/Activate.ps1

(Linux) source bin/activate

3. Install the 'requirements.txt' dependancies to ensure all the current functions of the bot work properly

Connecting to Discord

You will need to create a 'bot.conf' file that is in an INI format. Under the "Bot" header you will need to add the TOKEN key with your Discord bot token. Beyond that, it should all just work out of the box.

Additional Tokens

There might be additional service that exist that have been added over time that will require their own API key. You are responsible for providing it if you would like to either use or test new features with the bot using that service.

Recent Major Updates (v1.1.0)

Fully-Featured Platform Complete

We've just completed a massive overhaul that transforms GizmoBot into a truly "fully-featured" Discord bot platform:

Web-based Onboarding System

• Beautiful, responsive setup wizard at http://localhost:8000
• No more environment variable editing - everything through web interface
• Token validation, database initialization, and configuration all handled
• Perfect for self-hosting with zero technical setup

Real-time WebSocket Infrastructure

• Live dashboard updates without page refresh
• Real-time console log streaming to admin panel
• WebSocket subscription system for guild/admin/console events
• Connection management with automatic reconnection

Enhanced Plugin Architecture

• Multi-file plugin support for better organization
• Per-plugin per-guild database namespaces (guild_123_plugin_name_collection)
• Resource limiting and usage tracking for compute-heavy plugins
• Core vs Extra plugin classification system

Advanced Message Scheduling

• Rich embed builder with Discord validation
• Schedule messages up to 3 months in advance
• 15-minute interval enforcement as requested
• Draft/schedule/send workflow with templates

Live Admin Console

• Real-time log streaming with filtering
• System monitoring and bot status
• Plugin management and reloading
• Performance metrics and analytics

Smart Startup System

• Automatic first-run detection
• API-only mode for onboarding when bot can't start
• Seamless migration from environment variables
• Full bot mode when configuration is complete

Quick Start

# Clone and start - no configuration needed!
git clone https://github.com/yourusername/GizmoBot.git
cd GizmoBot

# Install dependencies and start
pip install -r requirements.txt
python main.py

# Visit http://localhost:8000 and complete the web setup wizard

Zero-Config Architecture

GizmoBot is designed to work out of the box with minimal setup:

• No Environment Variables Required: Auto-discovers MongoDB, generates secure keys
• Database-First Configuration: All bot settings stored securely in MongoDB
• Web-Based Setup: Complete onboarding process through browser interface
• Auto-Discovery: Finds MongoDB on localhost, Docker, or custom URI
• Secure by Default: Generates cryptographically secure JWT secrets automatically

Clean Architecture

We've streamlined the codebase to focus on the enhanced architecture:

• Removed: Legacy src/ directory and old command structure
• Unified: Single requirements.txt with all dependencies
• Simplified: Docker setup with single container for bot+API
• Modern: Database-first configuration via web interface

Key Files Created

• main.py - New enhanced entry point with startup detection
• bot/services/onboarding.py - Complete setup workflow
• api/core/websocket.py - Real-time WebSocket infrastructure
• bot/plugins/enhanced_base.py - Advanced plugin architecture
• bot/services/message_scheduler.py - Rich scheduling system
• web/static/ - Beautiful onboarding interface

---

Legacy Setup Instructions

Environment Setup

1. Setup a virtual environment: py -3.12 -m venv
2. Activate your virtual environment
3. Install dependencies: pip install -r requirements.txt

Connecting to Discord

NEW: Use the web interface! Just run python main.py and visit http://localhost:8000

Legacy: Create a 'bot.conf' file in INI format with your Discord bot token under the "Bot" header.

Repo Rules

1. No contributor is permitted to push changes to master except for the owner of the Repo
2. If you would like to begin working on the bot, please create a branch and create a pull request once your feature is complete
3. The repo owner's decisions on the direction for the repo and the code are made at their discretion