# modmail-dev/modmail architecture

> Architecture diagram of the GitHub repository modmail-dev/modmail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modmail-dev/modmail
- Repository: https://github.com/modmail-dev/modmail

## Overview

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: [`core/thread.py`](https://github.com/modmail-dev/modmail/blob/master/core/thread.py) (Thread lifecycle), [`bot.py`](https://github.com/modmail-dev/modmail/blob/master/bot.py) (Bot runtime), [`cogs/modmail.py`](https://github.com/modmail-dev/modmail/blob/master/cogs/modmail.py) (Modmail commands), [`core/clients.py`](https://github.com/modmail-dev/modmail/blob/master/core/clients.py) (API and database clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_bot["Bot runtime<br/>[bot.py]"]
end

subgraph group_threads["Thread workflow"]
  node_modmail["Modmail commands<br/>[modmail.py]"]
  node_thread["Thread lifecycle<br/>[thread.py]"]
  node_logs[("Thread logs<br/>[clients.py]")]
  node_logviewer["Logviewer"]
end

subgraph group_persistence["Configuration and data"]
  node_config["Configuration<br/>[config.py]"]
  node_permissions["Permission checks<br/>[checks.py]"]
  node_models["Shared models<br/>[models.py]"]
  node_api["API and database clients<br/>[clients.py]"]
end

subgraph group_commands["Commands and extensions"]
  node_plugins["Plugin commands<br/>[plugins.py]"]
  node_plugin_registry["Plugin registry<br/>[registry.json]"]
  node_threadmenu["Thread creation menus<br/>[threadmenu.py]"]
  node_utility["Utility commands<br/>[utility.py]"]
end

subgraph group_shared["Shared services"]
  node_paginator["Pagination UI<br/>[paginator.py]"]
  node_time["Time parsing<br/>[time.py]"]
  node_changelog["Changelog service<br/>[changelog.py]"]
  node_utils["Shared utilities<br/>[utils.py]"]
  node_colors["Color data<br/>[_color_data.py]"]
end

node_member(("Member"))
node_staff(("Server staff"))
node_discord(("Discord"))

node_member -->|"sends DM"| node_discord
node_discord -->|"delivers DM"| node_bot
node_bot -->|"finds or creates"| node_thread
node_thread -->|"creates channel"| node_discord
node_thread -->|"relays messages"| node_staff
node_staff -->|"replies in"| node_thread
node_thread -->|"relays replies"| node_member
node_modmail -->|"manages threads"| node_thread
node_thread -->|"uses clients"| node_api
node_api -->|"stores log data"| node_logs
node_thread -->|"publishes log link"| node_logviewer
node_logviewer -->|"shows saved threads"| node_logs
node_bot -->|"loads settings"| node_config
node_bot -->|"initializes clients"| node_api
node_bot -->|"imports lifecycle"| node_thread
node_modmail -->|"checks access"| node_permissions
node_plugins -.->|"lists plugins"| node_plugin_registry
node_bot -.->|"supports extensions"| node_plugins
node_bot -.->|"offers creation menus"| node_threadmenu
node_utility -->|"paginates results"| node_paginator
node_modmail -->|"uses pagination"| node_paginator
node_utility -->|"shows changelog"| node_changelog
node_modmail -->|"parses schedules"| node_time
node_config -->|"loads colors"| node_colors
node_config -->|"parses durations"| node_time
node_api -->|"uses shared types"| node_models
node_thread -->|"uses helpers"| node_utils
node_bot -->|"uses shared types"| node_models

click node_bot "https://github.com/modmail-dev/modmail/blob/master/bot.py"
click node_modmail "https://github.com/modmail-dev/modmail/blob/master/cogs/modmail.py"
click node_thread "https://github.com/modmail-dev/modmail/blob/master/core/thread.py"
click node_logs "https://github.com/modmail-dev/modmail/blob/master/core/clients.py"
click node_config "https://github.com/modmail-dev/modmail/blob/master/core/config.py"
click node_permissions "https://github.com/modmail-dev/modmail/blob/master/core/checks.py"
click node_models "https://github.com/modmail-dev/modmail/blob/master/core/models.py"
click node_api "https://github.com/modmail-dev/modmail/blob/master/core/clients.py"
click node_plugins "https://github.com/modmail-dev/modmail/blob/master/cogs/plugins.py"
click node_plugin_registry "https://github.com/modmail-dev/modmail/blob/master/plugins/registry.json"
click node_threadmenu "https://github.com/modmail-dev/modmail/blob/master/cogs/threadmenu.py"
click node_utility "https://github.com/modmail-dev/modmail/blob/master/cogs/utility.py"
click node_paginator "https://github.com/modmail-dev/modmail/blob/master/core/paginator.py"
click node_time "https://github.com/modmail-dev/modmail/blob/master/core/time.py"
click node_changelog "https://github.com/modmail-dev/modmail/blob/master/core/changelog.py"
click node_utils "https://github.com/modmail-dev/modmail/blob/master/core/utils.py"
click node_colors "https://github.com/modmail-dev/modmail/blob/master/core/_color_data.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bot toneBlue
class node_modmail,node_thread,node_logs,node_logviewer toneAmber
class node_config,node_permissions,node_models,node_api,node_staff toneMint
class node_plugins,node_plugin_registry,node_threadmenu,node_utility toneRose
class node_paginator,node_time,node_changelog,node_utils,node_colors,node_member,node_discord toneIndigo
```

## Components

### Bot runtime

- [Bot runtime](https://github.com/modmail-dev/modmail/blob/master/bot.py): `bot.py`

### Thread workflow

- [Modmail commands](https://github.com/modmail-dev/modmail/blob/master/cogs/modmail.py): `cogs/modmail.py`
- [Thread lifecycle](https://github.com/modmail-dev/modmail/blob/master/core/thread.py): `core/thread.py`
- [Thread logs](https://github.com/modmail-dev/modmail/blob/master/core/clients.py): `core/clients.py`
- **Logviewer**

### Configuration and data

- [Configuration](https://github.com/modmail-dev/modmail/blob/master/core/config.py): `core/config.py`
- [Permission checks](https://github.com/modmail-dev/modmail/blob/master/core/checks.py): `core/checks.py`
- [Shared models](https://github.com/modmail-dev/modmail/blob/master/core/models.py): `core/models.py`
- [API and database clients](https://github.com/modmail-dev/modmail/blob/master/core/clients.py): `core/clients.py`

### Commands and extensions

- [Plugin commands](https://github.com/modmail-dev/modmail/blob/master/cogs/plugins.py): `cogs/plugins.py`
- [Plugin registry](https://github.com/modmail-dev/modmail/blob/master/plugins/registry.json): `plugins/registry.json`
- [Thread creation menus](https://github.com/modmail-dev/modmail/blob/master/cogs/threadmenu.py): `cogs/threadmenu.py`
- [Utility commands](https://github.com/modmail-dev/modmail/blob/master/cogs/utility.py): `cogs/utility.py`

### Shared services

- [Pagination UI](https://github.com/modmail-dev/modmail/blob/master/core/paginator.py): `core/paginator.py`
- [Time parsing](https://github.com/modmail-dev/modmail/blob/master/core/time.py): `core/time.py`
- [Changelog service](https://github.com/modmail-dev/modmail/blob/master/core/changelog.py): `core/changelog.py`
- [Shared utilities](https://github.com/modmail-dev/modmail/blob/master/core/utils.py): `core/utils.py`
- [Color data](https://github.com/modmail-dev/modmail/blob/master/core/_color_data.py): `core/_color_data.py`

### Other components

- **Member**
- **Server staff**
- **Discord**

## Connections

- Member → Discord: sends DM (evidence: `README.md`)
- Discord → Bot runtime: delivers DM (evidence: `README.md`)
- Bot runtime → Thread lifecycle: finds or creates (evidence: `bot.py`)
- Thread lifecycle → Discord: creates channel (evidence: `core/thread.py`)
- Thread lifecycle → Server staff: relays messages (evidence: `README.md`)
- Server staff → Thread lifecycle: replies in (evidence: `README.md`)
- Thread lifecycle → Member: relays replies (evidence: `README.md`)
- Modmail commands → Thread lifecycle: manages threads (evidence: `cogs/modmail.py`)
- Thread lifecycle → API and database clients: uses clients (evidence: `core/thread.py`)
- API and database clients → Thread logs: stores log data (evidence: `core/clients.py`)
- Thread lifecycle → Logviewer: publishes log link (evidence: `README.md`)
- Logviewer → Thread logs: shows saved threads (evidence: `README.md`)
- Bot runtime → Configuration: loads settings (evidence: `bot.py`)
- Bot runtime → API and database clients: initializes clients (evidence: `bot.py`)
- Bot runtime → Thread lifecycle: imports lifecycle (evidence: `bot.py`)
- Modmail commands → Permission checks: checks access (evidence: `cogs/modmail.py`)
- Plugin commands → Plugin registry: lists plugins
- Bot runtime → Plugin commands: supports extensions (evidence: `README.md`)
- Bot runtime → Thread creation menus: offers creation menus (evidence: `README.md`)
- Utility commands → Pagination UI: paginates results (evidence: `cogs/utility.py`)
- Modmail commands → Pagination UI: uses pagination (evidence: `cogs/modmail.py`)
- Utility commands → Changelog service: shows changelog (evidence: `core/changelog.py`)
- Modmail commands → Time parsing: parses schedules (evidence: `cogs/modmail.py`)
- Configuration → Color data: loads colors (evidence: `core/config.py`)
- Configuration → Time parsing: parses durations (evidence: `core/config.py`)
- API and database clients → Shared models: uses shared types (evidence: `core/clients.py`)
- Thread lifecycle → Shared utilities: uses helpers (evidence: `core/thread.py`)
- Bot runtime → Shared models: uses shared types (evidence: `bot.py`)
