Skip to content

MonishKrishna2009/Apatite-Bot

BranchesTags

Repository files navigation

🎮 Apatite Bot

Discord.js   Bun   MongoDB   GitHub license  

⚡ Discord bot for esports matchmaking, community management, and moderation.

Important

This project is actively maintained and production-ready. The LFP/LFT system is fully implemented and stable. Here is the development roadmap for this project!

A feature-rich Discord bot built with discord.js v14 and MongoDB, designed for ticketing, player/team matchmaking (LFP/LFT), comprehensive logging, and advanced moderation tools. Perfect for gaming communities, esports servers, and competitive Discord servers.

📚 Table of Contents

Note

Want to try the bot out? You can join this server here: Apatite Esports

✨ Features

Caution

Most of the documentation is AI-generated. While it has been reviewed by a human, some errors may still be present. If you notice any, please open an issue or submit a pull request.

  • 👥 LFP / LFT System ✅

    • Multi-game Support: Valorant, CS2, League of Legends (easily extensible)
    • JSON Configuration: Games and fields defined in config files, no code changes needed
    • Dynamic Modals: Modal fields generated automatically from JSON configuration
    • Staff Review System: Comprehensive approvals/declines with advanced staff tools
    • Auto-cleanup: Enhanced cleanup with multiple types and dry run mode
    • User Controls: Create, edit, cancel, resend requests with validation
    • Game-Specific Channels: Separate review and public channels for each game
    • Comprehensive Notifications: Detailed DM notifications for all actions
    • Security & Validation: Input sanitization, rate limiting, cross-guild protection
    • Performance: Database indexes, timeout handling, error recovery
    • Message Recovery: Automatic recovery of accidentally deleted messages
    • Enhanced Staff Tools: Complete /lfstaff command suite with analytics
    • Recent Improvements: Better field name formatting, content length limits, null safety
    • Read More →

  • 🎫 Ticket System ✅

    • Multi-Type Support: Appeal, Claim Prize, General Inquiry, Production Inquiry
    • Automated Creation: Button-based ticket creation with type selection
    • Staff Management: Close, reopen, delete, and transcript generation
    • Transcript System: Automatic conversation logging and archiving
    • Permission Control: Role-based access and ownership validation
    • Dashboard Setup: Easy server setup with /ticket-setup command
    • Read More →

  • 🛡 Moderation Tools ✅

    • Message Management: Bulk message deletion with /purge command
    • Role-Based Permissions: Comprehensive permission validation
    • Staff Commands: Developer-only commands for bot management
    • Action Logging: Complete audit trail for all moderation actions
    • Read More →

  • 📜 Advanced Logging System ✅

    • Complete Event Coverage: 23+ Discord events including bans, invites, threads, webhooks, emojis, stickers
    • Privacy-First Design: GDPR/CCPA compliant with PII redaction and content sanitization
    • Hybrid Data Cleanup: MongoDB + Discord API integration for reliable data retention
    • Smart Retention Policies: Configurable retention periods (30 days content, 1 year metadata, 7 years audit)
    • Opt-in Content Logging: Full message content logging disabled by default for privacy
    • Audit Trail: Complete executor tracking with Discord audit log integration
    • Professional Formatting: Clean embeds with timestamps and user avatars
    • Performance Optimized: Database indexes, rate limiting, and efficient cleanup cycles
    • Recent Improvements: Reduced logging verbosity, better error handling, config compatibility
    • Read More →

  • ⚙️ Advanced Architecture ✅

    • Modular Design: Organized handlers for commands, events, and components
    • Error Handling: Comprehensive error management and recovery
    • Database Integration: MongoDB with optimized schemas and indexes
    • Configuration Management: Environment-based configuration system
    • License Compliance: GPL v3.0 compliance with automated checking
    • Recent Improvements: Better null safety, type guards, async error handling
    • Read More →

Tip

Each system has its own dedicated .md file inside /docs. Start there if you're exploring a specific feature.

📂 Project Structure

src/
├── Commands/           # Slash Commands
│   ├── Admin/          # Administrative commands (Ticket Setup)
│   ├── Dev/            # Developer commands (Reload)
│   ├── Info/           # Information commands (Ping, ServerInfo, UserInfo)
│   ├── LookingForSystem/ # LFP/LFT commands
│   └── Moderation/    # Moderation commands (Purge)
├── Components/         # Interactive Components
│   ├── Buttons/        # Button handlers (Ticket, LF Review)
│   └── Modals/         # Modal handlers (LFP/LFT Creation/Edit)
├── Events/             # Event Listeners
│   ├── Client/         # Bot client events (Ready)
│   ├── Interaction/    # Interaction events (AutoComplete, ButtonCreate)
│   ├── Logger/         # Comprehensive logging events
│   └── Looking For System/ # LF-specific events
└── Structure/          # Core Architecture
    ├── Client/         # Bot client configuration
    ├── Configs/        # Configuration files and JSON configs
    ├── Functions/      # Utility functions and LF system helpers
    ├── Handlers/       # Base handlers for commands, events, components
    └── Schemas/        # MongoDB schemas

Note

Detailed architecture explanation: Read More →

🚀 Getting Started

Prerequisites

Caution

Ensure MongoDB is running before starting the bot, otherwise commands may fail.

Installation

git clone https://github.com/MonishKrishna2009/Apatite-Bot.git
cd apatite-bot
bun install

Setup

  1. Copy .env.example → .env and configure:
# Discord Stuff
TOKEN = ""
CLIENT_ID = ""
CLIENT_SECRET = ""

# Database Stuff
MONGO_URI = "" 

# Logging Stuff (Channel IDs only - Privacy controls in config.js)
LOG_WEBHOOK = ""
SERVER_LOG_CHANNEL_ID = ""
MEMBER_LOG_CHANNEL_ID = ""
VOICE_LOG_CHANNEL_ID = ""
MESSAGE_LOG_CHANNEL_ID = ""
WARN_LOG_CHANNEL_ID = ""


#Ticket Stuff
TICKET_LOG_CHANNEL_ID = ""
TICKET_DASH_CHANNEL_ID = ""
TICKET_SUPPORT_ROLE_ID = ""
TICKET_TRANSCRIPT_CHANNEL_ID = ""
TICKET_CATEGORY = ""

#LFP LFT Stuff
LF_ACTION_LOG_CHANNEL_ID = ""
LF_MOD_ROLE_ID = ""
  1. Fill your dev user/dev guild details in config.js
    // Bot admins and developers
    developers: [
        {
            name: "Monk",
            id: "1156911026164482078",
        }
    ],
    devGuilds: [
        {
          name: "Apatite",
          id: "1040507183080685658",
        },
      ],
  1. Run
bun index.js

Warning

Never commit your .env file. It contains sensitive tokens.

🛡️ System Status & Recent Enhancements

LFP/LFT System - Production Ready ✅

The LFP/LFT system has undergone a comprehensive audit and enhancement process, achieving 19/20 critical logical errors fixed (95%):

🔒 Security & Validation

  • Input sanitization and XSS protection
  • Rate limiting with operation-specific limits
  • Cross-guild protection mechanisms
  • Comprehensive permission and channel validation
  • Status transition validation with enforced rules

⚡ Performance & Reliability

  • 7 strategic database indexes for optimal performance
  • Comprehensive timeout handling for all operations
  • Error recovery with fallback mechanisms
  • Race condition prevention with atomic operations
  • Message recovery system for accidental deletions

🛠️ Enhanced Staff Tools

  • Complete /lfstaff command suite with advanced features
  • Multiple cleanup types (expire, archive, delete, full) with dry run mode
  • Detailed statistics and analytics
  • User request management and granular filtering
  • Batch operations for efficient processing

The system is now robust, secure, and highly reliable for production use!

Advanced Logging System - Production Ready ✅

The logging system has been completely overhauled with privacy-first design and comprehensive event coverage:

🔒 Privacy & Compliance

  • GDPR/CCPA Compliant: Automatic PII redaction and content sanitization
  • Privacy-First Defaults: Full message content logging disabled by default
  • User Rights Support: Data deletion, portability, and access request handling
  • Retention Policies: Configurable data retention with automatic cleanup

📊 Complete Event Coverage

  • 23+ Discord Events: Server, member, message, voice, ban, invite, thread, webhook, emoji, sticker events
  • Hybrid Data Cleanup: MongoDB tracking + Discord API integration for reliable retention
  • Smart Analytics: Anonymized performance metrics and cleanup statistics
  • Error Recovery: Comprehensive error handling with retry mechanisms

⚡ Performance & Reliability

  • Database Indexes: Optimized MongoDB queries for fast cleanup operations
  • Rate Limiting: Discord API rate limit handling and backoff strategies
  • Silent Operation: Minimal logging output with essential completion notifications
  • MongoDB Integration: Complete audit trails and cleanup statistics storage

The logging system is now enterprise-grade with full privacy compliance!

📑 Documentation

🛠 Tech Stack

✨ Star History

Star History Chart

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

📄 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0-or-later).

🔓 What this means:

  • ✅ Free to use - You can use this software for any purpose
  • ✅ Free to modify - You can change the code to suit your needs
  • ✅ Free to distribute - You can share copies with others
  • ✅ Source code available - Full source code is provided
  • ⚠️ Copyleft - Any derivative works must also be GPL v3.0 licensed

📋 Requirements for users:

  • Attribution - You must include the original copyright notice
  • License preservation - You must include the GPL v3.0 license text
  • Source code - If you distribute the software, you must provide source code
  • No additional restrictions - You cannot add proprietary restrictions

🔗 Legal Resources:

⚖️ Compliance:

This project includes automated license compliance checking to ensure all source files contain proper GPL v3.0 headers and that the project meets all legal requirements. (REFER THIS)

About

An open-source esports & community management Discord bot with ticketing, matchmaking, moderation, and tournament tools.

Topics

events automation mongodb gaming discord moderation logging discord-bot event-management matchmaking tournaments esports community-management competitive-gaming discordjs-v14

Resources

Readme

License

GPL-3.0 license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Contributors

Languages