sarah
ceaeabf57a
Some checks failed
Auto Build and Push Docker Image / build (push) Failing after 15s
76 lines
4.4 KiB
Markdown
76 lines
4.4 KiB
Markdown
# AI Agent Guide: Modular Discord Bot Architecture
|
|
|
|
This document is intended for AI agents to understand, recreate, or extend the `pixelpoebel` Discord bot. It describes the design patterns, conventions, and key considerations for this specific modular architecture.
|
|
|
|
## 🏗 Architecture Overview
|
|
|
|
The bot uses a **Modular Command & Event Loading** pattern with **ESM (ECMAScript Modules)** and **TypeScript**.
|
|
|
|
### Key Design Patterns:
|
|
1. **Extended Client Pattern:** We extend the `discord.js` `Client` class to hold global state like the `commands` Collection. This avoids global variables and improves type safety.
|
|
2. **Dynamic Discovery:** The `src/index.ts` entry point uses `readdirSync` and dynamic `import()` to automatically register any command or event found in the `src/commands` or `src/events` directories.
|
|
3. **Interface-Driven Commands:** All commands must implement the `Command` interface defined in `src/structures/Command.ts`.
|
|
4. **Persistent SQLite Database:** The bot uses `better-sqlite3` for data persistence. It's initialized in `src/structures/Database.ts` and stores data in the `data/` directory.
|
|
5. **Twitch Monitoring Service:** The `TwitchManager` in `src/structures/` handles periodic API polling and notification logic.
|
|
6. **Granular Permission Handling:** Commands like `twitch.ts` use manual permission checks (`interaction.memberPermissions.has(PermissionFlagsBits.Administrator)`) to allow a mix of public and restricted subcommands within a single command.
|
|
|
|
## 💾 Database Interaction
|
|
|
|
To use the database in any command or event:
|
|
```typescript
|
|
import { DB } from '../../structures/Database.js';
|
|
|
|
// Example: Get one row
|
|
const user = DB.get('SELECT * FROM mod_logs WHERE user_id = ?', userId);
|
|
|
|
// Example: Insert data
|
|
DB.run('INSERT INTO mod_logs (guild_id, user_id, action) VALUES (?, ?, ?)', guildId, userId, 'WARN');
|
|
```
|
|
|
|
**Persistence:** In Docker, the `data/` folder is mapped to a volume to ensure data survives container restarts.
|
|
|
|
## 📡 Twitch API Implementation
|
|
|
|
The bot uses the **Twitch Helix API** with a client credentials flow. It requires:
|
|
- `TWITCH_CLIENT_ID`
|
|
- `TWITCH_CLIENT_SECRET`
|
|
|
|
**Workflow:**
|
|
- `TwitchManager.getAccessToken()`: Handles token acquisition and automatic renewal.
|
|
- `TwitchManager.fetchStreamData(channelName)`: Helper for real-time status checks.
|
|
- `TwitchManager.checkStreams()`: Periodically checks the status of monitored streamers from the database.
|
|
- `TwitchManager.sendNotification()`: Constructs and sends an embed with live stream details to the designated Discord channel.
|
|
|
|
## 🚀 How to Extend
|
|
|
|
### Adding a Command:
|
|
1. Navigate to `src/commands/`.
|
|
2. Create a subfolder for the category (e.g., `utility`, `owner`, `moderation`).
|
|
3. Create a file (e.g., `ping.ts`).
|
|
4. Implement the `Command` interface and `export default`.
|
|
5. Run `npm run deploy` (or use `/deploy` in Discord) to register it with Discord.
|
|
|
|
### Adding an Event:
|
|
1. Navigate to `src/events/`.
|
|
2. Create a file (e.g., `messageCreate.ts`).
|
|
3. `export default` an object with `name`, `once` (optional), and `execute`.
|
|
|
|
## ⚠️ Critical AI Agent Constraints
|
|
|
|
1. **Environment Variables:** Always use `process.env.DISCORD_TOKEN`, `CLIENT_ID`, `TWITCH_CLIENT_ID`, and `TWITCH_CLIENT_SECRET`. **Never hardcode credentials.**
|
|
2. **Type-Safe Casting:** When using `interaction.options.getMember('target')`, always cast to `GuildMember` if you need guild-specific methods like `.kick()`.
|
|
3. **Interaction States:** Remember to check `interaction.replied` or `interaction.deferred` before replying in error handlers to avoid "Interaction already replied" errors.
|
|
4. **Deployment:** Slash commands are NOT automatically registered on bot start. You MUST run the `deploy-commands.ts` script whenever the command data changes.
|
|
5. **Owner-Checks:** Use `client.application.owner` to verify permissions for owner-only commands.
|
|
|
|
## 📦 Replication Checklist for Agents
|
|
- [ ] Initialize NPM project with ESM.
|
|
- [ ] Set up `tsconfig.json` for NodeNext.
|
|
- [ ] Create `ExtendedClient.ts` to store commands.
|
|
- [ ] Create `index.ts` with dynamic folder loading logic.
|
|
- [ ] Create `deploy-commands.ts` for REST registration.
|
|
- [ ] Implement global error handling in `interactionCreate.ts`.
|
|
- [ ] Initialize SQLite database in `index.ts` via `DB.init()`.
|
|
- [ ] Set up `TwitchManager` for stream monitoring.
|
|
- [ ] Enable `Message Content Intent` in Discord Developer Portal if message tracking is needed.
|