Discord Bot Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Discord Bot Integration is a specialized module within the Tuturuuu ecosystem that bridges the platform's workspace management capabilities with Discord's communication environment. It allows users to link their authorized Discord servers to a Tuturuuu workspace, enabling automated reporting, link shortening, and interactive task management directly from Discord.
The integration is architected as a Python-based bot deployed via Modal, interacting with the core platform through Supabase for data persistence and Next.js-based dashboards for configuration. It provides a modular command structure and strict guild-level restrictions to ensure security and workspace alignment.
Sources: apps/discord/README.md:1-15, README.md:46-51
System Architecture
The integration follows a distributed architecture where the Discord Bot acts as a client to both the Discord API and the Tuturuuu backend services.
The diagram shows the interaction between the Discord Bot, the Supabase database, and the web-based management dashboard.
Sources: apps/discord/README.md:112-125, apps/web/src/app/[locale]/(dashboard)/[wsId]/integrations/discord/discord-integration-dashboard.tsx:50-100
Core Components
| Component | Responsibility | Technical Stack |
|---|---|---|
| Discord Client | Handles low-level API requests, message formatting, and interactive components. | Python / aiohttp |
| Management Dashboard | UI for connecting guilds, managing members, and configuring settings. | Next.js / TypeScript |
| Data Layer | Stores integration metadata, guild mappings, and linked members. | Supabase (PostgreSQL) |
| Deployment Host | Runs the bot as a serverless web app with cron support. | Modal |
Sources: apps/discord/README.md:112-125, apps/web/src/app/[locale]/(dashboard)/[wsId]/integrations/discord/discord-integration-dashboard.tsx:32-48, README.md:117-123
Integration Workflow
Connection and Authentication
Connecting a Discord server requires a verification process through the Web Dashboard. Users must provide a Discord Guild ID, which is then mapped to the Tuturuuu Workspace ID.
The sequence shows the handshake required to link a Discord guild to a platform workspace.
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/integrations/discord/discord-integration-dashboard.tsx:86-114, apps/web/src/app/[locale]/(dashboard)/[wsId]/integrations/discord/page.tsx:43-48
Member Mapping
The system allows linking platform users to Discord users via their unique Discord IDs (17-19 digit numeric strings). This is managed through the discord_guild_members table, which maps platform_user_id to discord_user_id.
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/integrations/discord/discord-integration-dashboard.tsx:169-200, apps/web/src/app/[locale]/(dashboard)/[wsId]/integrations/discord/page.tsx:51-68
Discord Client Logic
The DiscordClient class provides static methods for communicating with Discord's Webhook and REST API endpoints. It manages the formatting of complex UI elements like modals and select menus.
Interactive Components
The bot utilizes Discord's interactive components to handle complex workflows like ticket creation:
- Board Selection: Creates a select menu (type 3) containing up to 25 workspace boards.
- List Selection: Lists available task lists with status indicators (emojis).
- Ticket Modal: A type 9 component capturing task titles, descriptions, and priorities.
# Example Modal Structure
{
"type": 9,
"data": {
"custom_id": f"ticket_form|{board_id}|{list_id}",
"title": f"Create Ticket: {list_name}",
"components": [...]
}
}
Sources: apps/discord/discord_client.py:100-145, apps/discord/discord_client.py:215-265
Error Handling
The client implements specific exception classes for Discord-related failures:
DiscordMissingAccessError: Status 403, Code 50001 (Bot lacks channel access).DiscordMissingPermissionsError: Status 403, Code 50013 (Missing send/mention permissions).DiscordAPIError: General fallback for other status codes >= 400.
Sources: apps/discord/discord_client.py:10-25, apps/discord/discord_client.py:180-205
Bot Commands and Features
The bot provides several slash commands configured via the Discord Developer Portal and registered through Modal deployment scripts.
| Command | Functionality | Source File |
|---|---|---|
/api | Retrieves info about a random public API. | apps/discord/README.md |
/shorten | Shortens a URL using the Tuturuuu platform. | apps/discord/README.md |
/wol-reminder | Triggers a "Working Out Loud" daily priority reminder. | apps/discord/README.md |
Sources: apps/discord/README.md:127-160
Automated Reports
A "Daily Report Automation" feature posts nightly time-tracking summaries. This is configured via environment variables:
DISCORD_DAILY_REPORT_WORKSPACE_ID: Targets the correct platform workspace.DISCORD_DAILY_REPORT_CHANNEL: Specific channel ID for report output.
Sources: apps/discord/README.md:86-90
Configuration and Deployment
The integration relies on Modal Secrets for sensitive credentials.
Required Secrets
| Secret Key | Description |
|---|---|
DISCORD_BOT_TOKEN | Discord application bot token. |
DISCORD_CLIENT_ID | Application ID from Discord Developer Portal. |
DISCORD_PUBLIC_KEY | Used for validating incoming interactions. |
SUPABASE_URL | Workspace database URL. |
SUPABASE_SECRET_KEY | Service role key for administrative access. |
Sources: apps/discord/README.md:46-64
Testing Guidelines
The integration includes a comprehensive testing suite using pytest and ruff. Tests cover:
- Daily Reports: Validating formatting and data retrieval.
- WOL Reminders: Checking permission logic and channel posting.
- Type Safety: Enforced via
mypywith a target for Python 3.13+.
Sources: apps/discord/TESTING.md:1-50
Conclusion
The Discord Bot Integration extends the reach of the Tuturuuu platform into team communication channels. By combining serverless execution through Modal with robust member mapping and interactive Discord components, the system enables a seamless flow of task and reporting data between the web platform and Discord guilds. This integration is crucial for the platform's vision of reducing digital noise and context-switching for modern teams.
Sources: README.md:11-15, apps/discord/README.md:10-20