Professional Moderation Bot (EN)

Advanced, modular moderation bot compatible with Discord.js v14. Powered by MongoDB and Mongoose, designed for scalability.

For Turkish users, please see the README_TR.md file.

Quick Links

• Project Overview
• Setup & Configuration
• Troubleshooting
• Notes
• Roadmap

---

1. Project Overview

This project is a comprehensive moderation and registration bot developed for Discord servers. It runs on Node.js, uses MongoDB as its database, and is built on the latest Discord.js (v14) library. It includes systems for registration, penalties, user statistics, and staff promotions (upstaff).

Stack:

• Node.js
• Discord.js v14
• MongoDB (Mongoose)

2. What Changed?

Key changes and improvements in this version:

• Project Naming: All references to "acar" in files and folders have been removed and replaced with logical, English naming conventions (e.g., acar.js -> index.js).
• Architecture Improvements: The codebase has been separated into Service, Repository, and Worker layers for a cleaner structure.
• Registration Refactor: IsimKayıt.js has been rewritten to be button-based, secure, and built on the RegisterService.
• Penalty Scanning: Checks for expired penalties have been moved from the main flow to a background PenaltyWorker.js.
• Database Integration: Legacy or ad-hoc database calls have been standardized; connection management is optimized via mongoConnect.js.
• Security Enhancements: Sensitive data like Tokens and Mongo URIs have been centralized in configuration files.

3. Architecture Summary

The project follows a layered architecture where responsibilities are separated:

• src/Models: MongoDB schemas (User, Penalty, etc.).
• src/Repositories: Data Access Layer for database queries.
• src/Services: Business Logic layer (RegisterService, CoinsService).
• src/Workers: Background periodic tasks (PenaltyWorker).
• src/Events: Discord event handlers.
• src/Commands: User commands.

Folder Structure:

src/
├── Commands/       # Commands
├── Events/         # Event Handlers
├── Models/         # Mongoose Schemas
├── Repositories/   # Data Access Layer
├── Services/       # Business Logic
├── Settings/       # Config Files (json/js)
└── Workers/        # Background Workers

4. Setup & Configuration

Installation

1. Install required packages:

   npm install

2. Start the bot:

   node index.js

   (Or using pm2 start index.js)

Configuration Files (src/Settings/)

Editing these files is MANDATORY for the bot to function:

• system.js: Contains Bot Token and Mongo URI.
  • MongoURI: Your MongoDB connection string.
  • token: Discord Bot Token.
• roller.json: Role IDs for the server (Staff, Registered, Jail, etc.).
• kanallar.json: Channel IDs (Log channels, Chat, Registry, etc.).
• emojiler.json: Emoji IDs used in messages.
• extends.json: Server-specific general settings (Tag, Server Name, etc.).

5. Running & Operations

• Permissions: The bot requires Administrator permission or specific roles configured in roller.json to operate.
• Worker System: PenaltyWorker runs every 10 seconds to automatically remove expired penalties like Mutes and Jails.
• Registration & Logs:
  • Registration is handled via .kayıt command or buttons.
  • Transaction logs are sent to the log channels defined in kanallar.json.

6. Troubleshooting

• MongoDB Connection Error: Check the MongoURI value in system.js. Ensure there are no IP restrictions.
• Commands Not Working: Ensure Intents (Message Content, Server Members) are enabled in the Discord Developer Portal.
• Role Not Found Error: Verify that the IDs in roller.json match the current role IDs in your server.
• Bot Won't Start: Check that discord.js in package.json is v14 and your Node.js version is compatible (Recommended: 16+).
• Emoji Errors: If you see undefined or weird characters in bot messages, check emojiler.json.

7. Notes

• This bot is optimized for a specific server structure. It will not work at full capacity without proper role and channel configuration.
• The guardConfig settings in extends.json manage basic protection features (anti-swear/anti-ad).
• This project was created using Claude Sonnet 4.5 and Gemini 3 Pro.

8. Roadmap

• Dynamic Configuration: Managing system settings (roles, channels, limits) via Discord commands instead of JSON files.
• Web Dashboard: A web interface for easier management.
• Voice Analysis: Advanced voice activity tracking and scoring.