🤖 Advanced Discord Bot (ADB)

🚀 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

---

📊 Project Statistics

Stars

Forks

Open Issues

Pull Requests

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	💰 Daily Rewards	📝 Feedback Collection
💡 Suggestions	🏆 Leaderboards	📋 Main Menu
😂 Memes	📊 Performance Dashboard	⏰ 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. Commands sync per guild at startup and after supported plugin changes. For an explicit deployment, set CLIENT_ID and GUILD_ID, inspect node deploy-commands.js --dry-run, then run npm run deploy. The deploy command never overwrites global commands and refuses an empty command set unless --allow-empty is explicitly supplied.

For example, installing adb-plugin-moderation adds /ban, /kick, /timeout, /warn, /purge, and ticket commands; adb-plugin-levels adds /level and /leaderboard. Temporary voice controls use /voice <subcommand> so they do not collide with moderation's /lock and /unlock. See each plugin's own README for its command reference, and CREATE-PLUGIN.md to build your own.

---

Quick Start

Prerequisites

• Node.js v20.0.0 or higher (Node 22 or 24 recommended)
• MongoDB database, local or cloud
• Discord Bot Token from the Discord Developer Portal
• Google Gemini API Key from Google AI Studio, optional unless AI features are enabled

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          # required for the manual deploy command
   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.

   Enable Server Members, Message Content, and Presence gateway intents in the Discord Developer Portal to match the client's requested intents. Invite the bot with the bot and applications.commands scopes.

4. Deploy slash commands

   npm run deploy

5. Start the bot

    npm start

   An incomplete optional dashboard configuration disables the API without preventing bot startup. SIGINT and SIGTERM stop tasks, plugins, workers, Discord and database connections. Core schedules use UTC. Welcome messages come from the configured welcome plugin, not an unsolicited core fallback.

Verification

See verification and local plugin setup for test commands, the disposable-MongoDB integration check, and using edited sibling plugins rather than older npm releases. Music requires an external Lavalink v4 server; a successful offline test is not proof of live voice playback.

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
   # Docker: "mongo" is the compose service name; creds must match MONGO_INITDB_ROOT_* below
   MONGO_INITDB_ROOT_USERNAME=adb
   MONGO_INITDB_ROOT_PASSWORD=pick_a_long_random_password
   MONGODB_URI=mongodb://adb:pick_a_long_random_password@mongo:27017/discord-bot?authSource=admin
   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:

• CREATE-PLUGIN.md - build a plugin
• REGISTRY-SETUP.md - create or operate a plugin registry
• PLUGINS-ROADMAP.md - platform architecture and roadmap

---

🛠️ Technical Architecture

Modern Tech Stack

• Discord.js v14 - Discord API wrapper
• Node.js 20+ - 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.

🏆 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