Alex Support Bot

A professional Discord support bot with integrated bug reporting system, ticket management, and secure file storage on Cloudflare R2.

🚀 Features

• Bug Report System - Users submit bug reports via Discord modals
• Ticket Management - Automatic unique ticket ID generation (BUG-XXXXX format)
• File Upload - Secure file uploads to Cloudflare R2 cloud storage
• Database - MongoDB for persistent ticket and metadata storage
• Status Dashboard - Real-time system status monitoring
• Notifications - Role-based notification system with configurable mentions
• Error Handling - Comprehensive error logging and recovery mechanisms

📋 Prerequisites

Before you start, make sure you have:

• Node.js 18+ (Download here)
• MongoDB (local or cloud instance like MongoDB Atlas)
• Discord Bot Token with proper intents enabled
• Cloudflare R2 bucket (for file storage - optional but recommended)
• Git for version control

⚙️ Setup Guide

Step 1: Clone the Repository

git clone https://github.com/KanaparthyPraveen/Alex-support-bot.git
cd Alex-support-bot

Step 2: Install Dependencies

npm install

Step 3: Configure Environment Variables

Copy the example env file and update with your actual credentials:

cp .env.example .env

Now open .env and fill in the following variables:

Discord Configuration

DISCORD_TOKEN=your_discord_bot_token_here
TARGET_IDS=user_id_1,user_id_2,user_id_3
CHANNEL_ID=your_dashboard_channel_id
NOTIFICATION_CHANNEL_IDS=notification_channel_id_1,notification_channel_id_2

• DISCORD_TOKEN - Get this from Discord Developer Portal
• TARGET_IDS - Comma-separated list of Discord user IDs to monitor
• CHANNEL_ID - Channel ID where the status dashboard will be posted
• NOTIFICATION_CHANNEL_IDS - Channels for notifications (comma-separated)

MongoDB Configuration

MONGODB_URI=mongodb://localhost:27017/alex_support

• Local MongoDB: mongodb://localhost:27017/alex_support
• MongoDB Atlas Cloud: mongodb+srv://username:password@cluster.mongodb.net/alex_support

Cloudflare R2 Configuration (for file uploads)

R2_ACCESS_KEY_ID=your_r2_access_key
R2_SECRET_ACCESS_KEY=your_r2_secret_key
R2_BUCKET_NAME=bug-reports
R2_ENDPOINT=https://your-account.r2.cloudflarestorage.com

Get these from your Cloudflare R2 bucket settings

Role IDs for Notifications (optional)

ROLE_ID_OUTAGES=role_id_outages
ROLE_ID_UPDATES=role_id_updates
ROLE_ID_STATUS=role_id_status
ROLE_ID_ANNOUNCEMENTS=role_id_announcements
ROLE_ID_CHANGELOGS=role_id_changelogs
ROLE_ID_BIG_ASS_PING=role_id_ping

These are Discord role IDs for targeted notifications. Leave blank if not needed.

Step 4: Run the Bot

Development Mode (with auto-reload):

npm run dev

Production Build (compile TypeScript):

npm run build
npm start

📁 Project Structure

src/
├── index.ts                 # Entry point - bot initialization
├── client.ts               # Discord client configuration
├── config.ts               # Environment variables management
├── database.ts             # MongoDB connection setup
├── dashboard.ts            # Status dashboard display logic
├── embeds.ts              # Discord embed builders
├── buttons.ts             # Button interaction handlers
├── types.ts               # TypeScript interfaces & types
│
├── models/
│   └── Ticket.ts         # MongoDB Ticket model
│
├── schemas/
│   └── BugReport.ts      # MongoDB BugReport schema
│
├── interactions/
│   ├── buttons/
│   │   ├── reportBug.ts           # Bug report button handler
│   │   └── notifications.ts       # Notification settings handler
│   ├── modals/
│   │   ├── productionReportModal.ts    # Bug report form
│   │   └── bugReportModal.ts           # Legacy bug report modal
│   ├── handlers/
│   │   ├── interactionHandler.ts         # Main interaction router
│   │   └── productionReportHandler.ts    # Process bug submissions
│   └── messages/
│       └── attachmentHandler.ts    # Handle message attachments
│
├── services/
│   └── r2Uploader.ts     # Cloudflare R2 file upload service
│
├── scripts/
│   ├── verify-fetch.ts   # Utility script
│   └── verify-r2.ts      # R2 verification script
│
└── utils/
    ├── generateTicketId.ts  # Create unique BUG-XXXXX IDs
    └── storage.ts          # Storage utility functions

🔄 How It Works

Bug Report Flow

1. User clicks "Report Bug" button in Discord
2. Modal appears asking for title, description, and optional environment info
3. User submits with optional file attachments
4. Bot processes:
   • Generates unique ticket ID (e.g., BUG-A1B2C)
   • Downloads files from Discord CDN
   • Uploads files to R2 storage
   • Saves ticket metadata to MongoDB
5. User receives ticket confirmation with ID for tracking

Data Storage

MongoDB stores:

• Ticket ID, user info, bug description
• File URLs from R2
• Status (OPEN, IN_PROGRESS, RESOLVED, CLOSED)
• Creation timestamp

R2 stores:

• Actual bug report files
• Organized by ticket ID: tickets/BUG-A1B2C/filename.ext

🧪 Testing

1. Click the "🐛 Report a Bug" button in Discord
2. Fill in the bug title and description
3. (Optional) Attach files to your Discord message before submitting
4. Submit the modal
5. Check:
   • Bot's Discord reply with ticket ID
   • MongoDB for new ticket record
   • R2 bucket for uploaded files

🚨 Troubleshooting

Bot not responding?

• Check Discord token is correct in .env
• Ensure bot has "Send Messages" permission in the channel
• Verify privileged intents are enabled in Developer Portal

Database connection error?

• Verify MONGODB_URI is correct
• Check MongoDB server is running (local) or connection string is valid (Atlas)
• Ensure network access is allowed if using MongoDB Atlas

R2 upload failing?

• Double-check R2 credentials in .env
• Verify bucket name is correct
• Check R2 endpoint URL format

No files uploading?

• Ensure R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY are valid
• Check bucket has proper permissions
• Verify file size is not too large

📝 Available Scripts

npm run dev       # Development mode with ts-node
npm run build     # Compile TypeScript to JavaScript
npm start         # Run production build (after npm run build)

🔐 Security Notes

• Never commit .env to version control
• Use .env.example as a template
• Keep Discord token, R2 keys, and MongoDB URI private
• Rotate credentials periodically
• Use environment-specific values for different environments

🏗️ Architecture Highlights

• Separation of Concerns - Each module has a single responsibility
• Type Safety - Full TypeScript for better development experience
• Error Handling - Comprehensive error catching and logging
• Async/Await - Modern async patterns throughout
• MongoDB Schemas - Structured data models with validation

📚 API Endpoints & Interactions

Button IDs

• btn_bug_report - Opens bug report modal
• btn_troubleshoot - Shows troubleshooting options
• btn_notifications_menu - Notification settings
• btn_role_* - Role toggle buttons

Modal IDs

• Production bug report modal
• Legacy bug report modal (backward compatible)

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Commit with clear messages
5. Push and create a pull request

📄 License

ISC

💬 Support

For issues or questions:

1. Check the troubleshooting section above
2. Review MongoDB and R2 documentation
3. Create an issue on GitHub with detailed steps to reproduce

🔗 Useful Links

• Discord.js Documentation
• MongoDB Documentation
• Cloudflare R2 Documentation
• Discord Developer Portal

---

Built with ❤️ for the Alex Music Bot community