Discord Bot Overview
The Smutje Discord bot (named after a ship's cook in German maritime tradition) is a Rust-based Discord bot that integrates deeply with the Heimdall platform. It enables server management, member moderation, and real-time data synchronization between Discord and the Heimdall backend.
Key Features
| Feature | Description |
|---|---|
| Slash Commands | Modern Discord slash commands with prefix fallback via Poise |
| Real-time Sync | Bidirectional WebSocket communication with Protobuf serialization |
| Guild Management | Sync and manage Discord servers, channels, roles, and members |
| Member Moderation | Warn, kick, ban, and timeout members from the Heimdall dashboard |
| RBAC Integration | Permission-based commands via Heimdall account linking |
| Audit Logging | All actions logged to Heimdall's audit system |
| Multi-language | English and German localization |
| Error Tracking | Sentry integration for monitoring |
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Discord API │
│ (Gateway + REST API) │
└─────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Smutje Discord Bot │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Poise Framework │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │
│ │ │ Commands │ │ Hooks │ │ Event Handlers │ │ │
│ │ │ (Slash/Txt) │ │ (Pre/Post) │ │ (Guild Events) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴────────────────────────────────┐ │
│ │ API Clients │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │ │
│ │ │ GraphQL │ │ REST │ │WebSocket │ │ Audit │ │ │
│ │ │ Client │ │ Client │ │ Client │ │ Client │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Heimdall API │
│ (GraphQL, REST, WebSocket endpoints) │
│ │ │
│ ┌───────────┐ ┌───────────┴───────────┐ ┌─────────────────┐ │
│ │ PostgreSQL│ │ WebSocket Server │ │ Audit System │ │
│ │ Database │ │ (Broadcast/Events) │ │ (Logging) │ │
│ └───────────┘ └───────────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
How It Works
1. Discord Commands
Users interact with the bot via slash commands (/ping, /help, /settings) or text commands (!ping). Commands can be public or require specific Heimdall permissions.
2. API Communication
The bot communicates with the Heimdall API using three protocols:
- WebSocket (Protobuf) - Real-time events, sync requests, moderation actions
- GraphQL - Queries and mutations for complex operations
- REST - Simple CRUD operations
3. Data Synchronization
The Heimdall backend can request the bot to sync Discord data:
- Guilds - Server metadata (name, icon, member count, boost level)
- Channels - All channel types with hierarchy
- Roles - Role metadata with permissions
- Members - Full member list with roles and status
4. Moderation Actions
Administrators can moderate Discord members directly from the Heimdall dashboard:
- Warn - Send a warning DM
- Kick - Remove from server
- Ban - Permanently ban
- Timeout - Temporarily mute
5. Audit Trail
Every action is logged to Heimdall's audit system with:
- Actor identification (Heimdall user ID if linked, Discord user ID)
- Action details and metadata
- Timestamps and source service tracking
Project Structure
platform/discord_bot/
├── Cargo.toml # Dependencies and metadata
├── config/ # Configuration files
│ ├── default.toml # Base configuration
│ ├── development.toml # Development overrides
│ └── production.toml # Production overrides
├── locales/ # Translation files
│ ├── en.yml # English
│ └── de.yml # German
├── src/
│ ├── main.rs # Entry point
│ ├── lib.rs # Library root with i18n setup
│ ├── bot/ # Poise framework setup
│ │ ├── mod.rs
│ │ ├── client.rs # Framework builder, event handlers
│ │ └── data.rs # Shared state (Data struct), Context type
│ ├── commands/ # Command implementations
│ │ ├── mod.rs # Command registration
│ │ ├── general.rs # Public commands (ping, help, info)
│ │ ├── admin.rs # Admin commands (config, settings)
│ │ └── moderate.rs # Moderation commands (warn, kick, ban)
│ ├── clients/ # API client implementations
│ │ ├── mod.rs
│ │ ├── graphql.rs # GraphQL client
│ │ ├── rest.rs # REST client
│ │ ├── websocket.rs # WebSocket client (Protobuf)
│ │ └── audit.rs # Audit logging client
│ ├── permissions/ # RBAC integration
│ ├── config/ # Configuration loading
│ ├── handlers/ # HTTP handlers (health endpoint)
│ ├── utils/ # Utilities (colors, rate limits)
│ ├── embeds/ # Embed builders
│ ├── error.rs # Error types
│ └── telemetry.rs # Sentry + tracing setup
└── tests/ # Integration tests
Technology Stack
| Component | Technology |
|---|---|
| Language | Rust 2024 Edition |
| Discord Library | Serenity |
| Command Framework | Poise |
| Async Runtime | Tokio |
| Serialization | Protobuf (prost), JSON (serde) |
| HTTP Client | reqwest |
| Configuration | config-rs + TOML |
| Localization | rust-i18n |
| Error Tracking | Sentry |
| Logging | tracing |
Documentation Guide
| Document | Description |
|---|---|
| Getting Started | Quick start guide, prerequisites, running the bot |
| Configuration | Configuration files and environment variables |
| Commands | Command system and creating new commands |
| Permissions | RBAC integration and permission checks |
| API Integration | GraphQL, REST, and WebSocket clients |
| Data Sync | Guild, channel, role, and member synchronization |
| Moderation | Member moderation features |
| Internationalization | Multi-language support |
| Embeds & UI | Discord embeds and UI components |
| Rate Limiting | Discord rate limit handling |