How modmail-dev/modmail works
Modmail is a Discord shared-inbox bot: a member’s DM starts a staff thread, messages are relayed between the member and staff, and closing the thread produces a log link for later review. The graph also shows configuration and permissions, plugins, thread-creation menus, and command utilities. The README documents the user-facing workflow and capabilities; source-index references and excerpts support several internal links. Some implementation details—especially log viewing and unsampled cog behavior—are documented but not visible in the excerpts.
Main entry points: thread.py Thread lifecycle · bot.py Bot runtime · modmail.py Modmail commands · clients.py API and database clients
Components 21
Bot runtime
- Bot runtime
bot.py
Thread workflow
- Modmail commands
cogs/modmail.py - Thread lifecycle
core/thread.py - Thread logs
core/clients.py - Logviewer
Configuration and data
- Configuration
core/config.py - Permission checks
core/checks.py - Shared models
core/models.py - API and database clients
core/clients.py
Commands and extensions
- Plugin commands
cogs/plugins.py - Plugin registry
plugins/registry.json - Thread creation menus
cogs/threadmenu.py - Utility commands
cogs/utility.py
Shared services
- Pagination UI
core/paginator.py - Time parsing
core/time.py - Changelog service
core/changelog.py - Shared utilities
core/utils.py - Color data
core/_color_data.py
Other components
- Member
- Server staff
- Discord
Connections 28
- Member → Discord: sends DM
README.md - Discord → Bot runtime: delivers DM
README.md - Bot runtime → Thread lifecycle: finds or creates
bot.py - Thread lifecycle → Discord: creates channel
core/thread.py - Thread lifecycle → Server staff: relays messages
README.md - Server staff → Thread lifecycle: replies in
README.md - Thread lifecycle → Member: relays replies
README.md - Modmail commands → Thread lifecycle: manages threads
cogs/modmail.py - Thread lifecycle → API and database clients: uses clients
core/thread.py - API and database clients → Thread logs: stores log data
core/clients.py - Thread lifecycle → Logviewer: publishes log link
README.md - Logviewer → Thread logs: shows saved threads
README.md - Bot runtime → Configuration: loads settings
bot.py - Bot runtime → API and database clients: initializes clients
bot.py - Bot runtime → Thread lifecycle: imports lifecycle
bot.py - Modmail commands → Permission checks: checks access
cogs/modmail.py - Plugin commands → Plugin registry: lists plugins
- Bot runtime → Plugin commands: supports extensions
README.md - Bot runtime → Thread creation menus: offers creation menus
README.md - Utility commands → Pagination UI: paginates results
cogs/utility.py - Modmail commands → Pagination UI: uses pagination
cogs/modmail.py - Utility commands → Changelog service: shows changelog
core/changelog.py - Modmail commands → Time parsing: parses schedules
cogs/modmail.py - Configuration → Color data: loads colors
core/config.py - Configuration → Time parsing: parses durations
core/config.py - API and database clients → Shared models: uses shared types
core/clients.py - Thread lifecycle → Shared utilities: uses helpers
core/thread.py - Bot runtime → Shared models: uses shared types
bot.py