Skip to content

README.md

Latest commit

 

History

History
450 lines (328 loc) · 14.2 KB

README.md

File metadata and controls

450 lines (328 loc) · 14.2 KB
Raw

🤖 Advanced Discord Bot (ADB)

Discord Bot Node.js MongoDB Gemini AI Plugin Ready License


Invite Bot Dashboard

🚀 ADB is a self-hosted Discord bot platform built to become whatever your server needs.
🔌 Install plugins • 🧩 Build your own modules • 🖥️ Manage everything from a dashboard • 🔓 Own the stack

Features Installation Commands Plugins Contributing

📊 Project Statistics

GitHub Stars
Stars 		GitHub Forks
Forks 		GitHub Issues
Open Issues 		GitHub Pull Requests
Pull Requests 		GitHub Contributors
Contributors

👑 Maintainer

Role Name GitHub
🛠️ Maintainer DeadIndian @DeadIndian

ADB is not participating in any open source contribution program at the moment. Contributions are reviewed through regular GitHub issues and pull requests.

🖼️ Screenshots

🎨 Feature Showcase

Birthday System 🎂 Birthday System Daily Points 💰 Daily Rewards Feedback Form 📝 Feedback Collection
Feedback Suggestions 💡 Suggestions Leaderboard 🏆 Leaderboards Main Menu 📋 Main Menu
Memes System 😂 Memes Performance Dashboard 📊 Performance Dashboard Reminder Setter ⏰ Reminders

✨ Why Choose ADB?

🔌 Plugin-first foundation - Add commands, dashboards, scheduled jobs, models, and hooks without editing core code
🖥️ Dashboard-ready - Built around a web control plane for server admins and plugin management
🛒 Marketplace-ready - Discover and install community plugins from a registry-backed marketplace
🎯 General or specialized - Run it as an all-in-one community bot or strip it down into a focused custom bot
🔓 Self-hosted ownership - Your bot, your data, your infrastructure, your rules
🛡️ Privacy-first - Data stays in your MongoDB instance instead of a third-party SaaS platform
🤖 AI capable - Google Gemini integration for assistant and FAQ-style workflows
⚡ Modern Discord stack - Discord.js v14, Node.js, MongoDB, Fastify/Express pieces, and hot-reloadable plugins

🎯 Features

ADB ships as a lean core plus a dashboard. Everything user-facing — moderation, levels, economy, giveaways, logging, and more — is delivered by plugins you install from the marketplace, so you run only what your server needs. See Plugins & Marketplace.

🔌 Plugin Platform

  • Local plugins from plugins/ and npm packages (adb-plugin-*)
  • Plugin manifests with metadata, config schemas, capabilities, and restart flags
  • Command registration and command overrides
  • Event listeners, scheduled jobs, hook bus, and namespaced database models
  • Sandboxed-by-default isolation — plugins run in a worker and reach Discord/DB only through capability-gated RPC

🖥️ Administration Dashboard

  • Discord OAuth-based admin access
  • Guild picker for server-specific management
  • Multi-tenant RBAC: derived HOST_OWNER / GUILD_ADMIN / MEMBER tiers, per-plugin dashboard permission keys, and an Access page to grant Discord roles fine-grained dashboard access
  • Per-guild plugin enable gate — installed plugins are off in each guild until an admin turns them on
  • Plugin install, enable, disable, and status views
  • Auto-generated settings pages from each plugin's config schema
  • Member-facing portal and per-plugin dashboards

🤖 AI Assistant (optional, via Gemini)

  • Google Gemini-powered responses when GEMINI_API_KEY is set
  • Configurable AI channels and behavior
  • Rate limiting and graceful failure handling

🧩 Official Plugins

Install from the registry — moderation, automod, aegis (anti-raid/spam/alt), levels & XP, giveaways, counting, confessions, autorole, reaction-roles, invite-tracker, reminders, server-logs, temp voice, welcome, custom commands, to-do, and more.

Commands

ADB has no built-in slash commands — commands come from the plugins you install. Each plugin registers its own; enable a plugin from the dashboard and run npm run deploy to publish its commands to Discord.

For example, installing adb-plugin-moderation adds /ban, /kick, /timeout, /warn, /purge, and ticket commands; adb-plugin-levels adds /rank and /leaderboard. See each plugin's own README for its command reference, and CREATE-PLUGIN.md to build your own.

Quick Start

Prerequisites

Option 1: Local Setup

  1. Clone the repository

    git clone https://github.com/AdvancedDiscordBot/Advanced-Discord-Bot.git
cd Advanced-Discord-Bot

  2. Install dependencies

    npm install

  3. Configure environment variables

    Copy .env.example to .env and fill in your values — it documents every variable. The essentials:

    DISCORD_TOKEN=your_discord_bot_token_here
CLIENT_ID=your_bot_client_id_here
GUILD_ID=your_test_guild_id_here          # optional: instant commands in one test guild
MONGODB_URI=your_mongodb_connection_string
GEMINI_API_KEY=your_gemini_api_key_here   # optional: only for AI features

# Dashboard / internal API (needed only if you use the web dashboard)
BOT_API_ENABLED=true
BOT_API_PORT=3210
DISCORD_OAUTH_CLIENT_ID=your_oauth_client_id
DISCORD_OAUTH_CLIENT_SECRET=your_oauth_client_secret
DISCORD_OAUTH_REDIRECT_URI=http://localhost:3210/auth/discord/callback
DASHBOARD_REDIRECT_URL=http://localhost:3000
SESSION_SECRET=replace_with_a_long_random_secret
# Comma-separated Discord user IDs of host owners — the top RBAC tier and the
# only one allowed to install/uninstall plugins. Set at least one.
OWNER_IDS=your_discord_user_id
# Optional: your plugin marketplace registry (see REGISTRY-SETUP.md)
PLUGIN_REGISTRY_URL=

    See .env.example for the full list of options.

  4. Deploy slash commands

    npm run deploy

  5. Start the bot

    npm start

Option 2: Docker Setup

  1. Clone the repository

    git clone https://github.com/AdvancedDiscordBot/Advanced-Discord-Bot.git
cd Advanced-Discord-Bot

  2. Configure environment variables

    Create a .env file (see .env.example for the full list). For the bundled MongoDB container, point MONGODB_URI at the mongo service:

    DISCORD_TOKEN=your_discord_bot_token_here
CLIENT_ID=your_bot_client_id_here
GUILD_ID=your_test_guild_id_here
MONGODB_URI=mongodb://advance:bot@mongo:27017/discord-bot?authSource=admin&retryWrites=true&w=majority
GEMINI_API_KEY=your_gemini_api_key_here
SESSION_SECRET=replace_with_a_long_random_secret

  3. Deploy slash commands

    docker compose run --rm bot npm run deploy

  4. Build and start

    docker compose up --build -d

  5. View logs

    docker compose logs -f bot

🌐 Deployment

ADB can run on Render, Railway, Fly.io, a VPS, or any host that supports Node.js and MongoDB access.

Recommended production steps:

  1. Set all required environment variables in your host dashboard.
  2. Use npm install as the build command.
  3. Use npm start as the start command.
  4. Run npm run deploy once after first deployment or after slash command changes.
  5. Point the dashboard URL and OAuth callback URLs at your deployed domain.

Suggested service name:

Advanced Discord Bot

🔧 Database Setup

MongoDB Options

Option 1: MongoDB Atlas

  1. Create a cluster at MongoDB Atlas
  2. Create a database user
  3. Allow your deployment host in Network Access
  4. Copy the connection string into MONGODB_URI

Option 2: Local MongoDB

mongod --dbpath ./data

Option 3: Docker Compose

Use the included docker-compose.yml to run MongoDB alongside the bot.

Database Features

  • Automatic schema creation
  • Persistent guild, user, ticket, economy, XP, birthday, and plugin config data
  • Plugin-specific model namespacing
  • Backup-friendly MongoDB storage

🔌 Plugins & Marketplace

ADB is designed to be extended. A plugin can:

  • Add slash commands
  • Override existing commands
  • Listen to Discord events
  • Register scheduled jobs
  • Define MongoDB models
  • Hook into bot flows
  • Expose its own dashboard
  • Provide a settings schema for generated admin UI

Start here:

🛠️ Technical Architecture

Modern Tech Stack

  • Discord.js v14 - Discord API wrapper
  • Node.js 18+ - JavaScript runtime
  • MongoDB + Mongoose - Persistent data and schemas
  • Google Gemini AI - AI assistant features
  • Fastify/Express - Dashboard and internal API surfaces
  • React - Administration dashboard

Core Runtime

  • Dynamic command and event loading
  • Plugin Manager and Hook Bus
  • Scheduled jobs via node-cron
  • MongoDB-backed guild and user configuration
  • Dashboard API for plugin and guild management

See ARCHITECTURE.md for implementation details.

📞 Support & Community

  • 📖 Documentation - Start with this README and the linked docs
  • 🐛 Bug Reports - Open a GitHub issue
  • 💡 Feature Requests - Open an issue with the feature proposal
  • 🔌 Plugin Ideas - Discuss or submit plugin-focused issues and PRs
  • 💬 Direct Contact - Email gollabharath2007@gmail.com or reach out via Discord to @deadindian

📄 License

This project is licensed under the GNU Affero General Public License v3.0. See LICENSE for details.

License: AGPL-3.0

🏆 Acknowledgments

  • Discord Developer Community - For tooling, examples, and ecosystem knowledge
  • Open Source Contributors - For improving the project through issues and PRs
  • Plugin Authors - For turning ADB into more than a single-purpose bot
  • Everyone self-hosting it - For shaping the project through real-world usage

🚀 Build The Bot Your Server Actually Needs

Self-hosted • Plugin-ready • Dashboard-managed

🌟 Star this repo • 🍴 Fork & Deploy • 📖 Read the docs

Maintained by @DeadIndian
"One base bot. Any use case."

⬆️ Back to Top