# pluralkit/pluralkit architecture

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

- Interactive diagram: https://gitdiagram.com/pluralkit/pluralkit
- Repository: https://github.com/pluralkit/pluralkit
- Video tour (about a minute): https://gitdiagram.com/pluralkit/pluralkit/video

## Overview

PluralKit is a Discord bot and companion service for plural communities. Its central workflow is Discord events reaching the bot, where messages can be matched to member proxy tags and relayed through webhooks; users also manage systems and members and track switches through commands. The repository additionally includes public/private APIs, a web dashboard, avatar processing, and dispatch integrations. The graph preserves these documented product areas, but several links are dashed where the sampled code does not show the runtime wiring.

Main entry points: [`PluralKit.Bot/Proxy/ProxyService.cs`](https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Bot/Proxy/ProxyService.cs) (Message proxying), [`PluralKit.Core/Database/Repository/ModelRepository.cs`](https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Core/Database/Repository/ModelRepository.cs) (Model repository), [`PluralKit.Core/Database/IDatabase.cs`](https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Core/Database/IDatabase.cs) (Postgres database), [`Myriad/Gateway/Shard.cs`](https://github.com/pluralkit/pluralkit/blob/main/Myriad/Gateway/Shard.cs) (Gateway shards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discord["Discord runtime"]
  node_gateway["Gateway shards<br/>[Shard.cs]"]
  node_gateway_state["Shard state"]
  node_bot["Bot event router<br/>[Bot.cs]"]
  node_handlers["Event handlers<br/>[Handlers]"]
  node_rest["Discord REST client"]
  node_cache["Discord cache<br/>[IDiscordCache.cs]"]
end

subgraph group_product["Bot features"]
  node_proxy["Message proxying<br/>[ProxyService.cs]"]
  node_commands["Bot commands<br/>[Commands]"]
  node_embeds["Profile rendering<br/>[EmbedService.cs]"]
end

subgraph group_data["Core data"]
  node_models["System and member models<br/>[Models]"]
  node_repository["Model repository<br/>[ModelRepository.cs]"]
  node_database[("Postgres database<br/>[IDatabase.cs]")]
end

subgraph group_interfaces["User interfaces"]
  node_api["HTTP API"]
  node_dashboard["Web dashboard<br/>[App.svelte]"]
end

subgraph group_services["Supporting services"]
  node_dispatch["Webhook dispatch<br/>[DispatchService.cs]"]
  node_avatars["Avatar processing<br/>[main.rs]"]
  node_background["Scheduled services<br/>[main.rs]"]
end

node_discord_users(("Discord users"))
node_discord(("Discord platform"))

node_discord -.->|"sends events"| node_gateway
node_gateway -->|"handles packets"| node_gateway_state
node_gateway -->|"raises events"| node_bot
node_bot -->|"routes events"| node_handlers
node_handlers -.->|"handles messages"| node_proxy
node_discord_users -.->|"issues commands"| node_commands
node_commands -->|"reads and writes"| node_repository
node_commands -->|"renders profiles"| node_embeds
node_proxy -.->|"loads proxy data"| node_repository
node_proxy -.->|"dispatches updates"| node_dispatch
node_proxy -.->|"relays messages"| node_rest
node_embeds -.->|"fetches Discord data"| node_rest
node_embeds -->|"fetches cached users"| node_cache
node_repository -.->|"queries data"| node_database
node_repository -.->|"loads models"| node_models
node_api -.->|"serves data"| node_database
node_dashboard -.->|"requests data"| node_api
node_avatars -.->|"stores avatar data"| node_database
node_background -.->|"runs scheduled work"| node_database

click node_gateway "https://github.com/pluralkit/pluralkit/blob/main/Myriad/Gateway/Shard.cs"
click node_gateway_state "https://github.com/pluralkit/pluralkit/blob/main/Myriad/Gateway/State/ShardStateManager.cs"
click node_bot "https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Bot/Bot.cs"
click node_handlers "https://github.com/pluralkit/pluralkit/tree/main/PluralKit.Bot/Handlers"
click node_proxy "https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Bot/Proxy/ProxyService.cs"
click node_commands "https://github.com/pluralkit/pluralkit/tree/main/PluralKit.Bot/Commands"
click node_embeds "https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Bot/Services/EmbedService.cs"
click node_models "https://github.com/pluralkit/pluralkit/tree/main/PluralKit.Core/Models"
click node_repository "https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Core/Database/Repository/ModelRepository.cs"
click node_database "https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Core/Database/IDatabase.cs"
click node_dispatch "https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Core/Dispatch/DispatchService.cs"
click node_rest "https://github.com/pluralkit/pluralkit/blob/main/Myriad/Rest/DiscordApiClient.cs"
click node_cache "https://github.com/pluralkit/pluralkit/blob/main/Myriad/Cache/IDiscordCache.cs"
click node_api "https://github.com/pluralkit/pluralkit/tree/main/crates/api/src/endpoints"
click node_dashboard "https://github.com/pluralkit/pluralkit/blob/main/dashboard/src/App.svelte"
click node_avatars "https://github.com/pluralkit/pluralkit/blob/main/crates/avatars/src/main.rs"
click node_background "https://github.com/pluralkit/pluralkit/blob/main/crates/scheduled_tasks/src/main.rs"

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_gateway,node_gateway_state,node_bot,node_handlers,node_rest,node_cache,node_discord_users toneBlue
class node_proxy,node_commands,node_embeds toneAmber
class node_models,node_repository,node_database toneMint
class node_api,node_dashboard toneRose
class node_dispatch,node_avatars,node_background,node_discord toneIndigo
```

## Components

### Discord runtime

- [Gateway shards](https://github.com/pluralkit/pluralkit/blob/main/Myriad/Gateway/Shard.cs): `Myriad/Gateway/Shard.cs`
- [Shard state](https://github.com/pluralkit/pluralkit/blob/main/Myriad/Gateway/State/ShardStateManager.cs): `Myriad/Gateway/State/ShardStateManager.cs`
- [Bot event router](https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Bot/Bot.cs): `PluralKit.Bot/Bot.cs`
- [Event handlers](https://github.com/pluralkit/pluralkit/tree/main/PluralKit.Bot/Handlers): `PluralKit.Bot/Handlers`
- [Discord REST client](https://github.com/pluralkit/pluralkit/blob/main/Myriad/Rest/DiscordApiClient.cs): `Myriad/Rest/DiscordApiClient.cs`
- [Discord cache](https://github.com/pluralkit/pluralkit/blob/main/Myriad/Cache/IDiscordCache.cs): `Myriad/Cache/IDiscordCache.cs`

### Bot features

- [Message proxying](https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Bot/Proxy/ProxyService.cs): `PluralKit.Bot/Proxy/ProxyService.cs`
- [Bot commands](https://github.com/pluralkit/pluralkit/tree/main/PluralKit.Bot/Commands): `PluralKit.Bot/Commands`
- [Profile rendering](https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Bot/Services/EmbedService.cs): `PluralKit.Bot/Services/EmbedService.cs`

### Core data

- [System and member models](https://github.com/pluralkit/pluralkit/tree/main/PluralKit.Core/Models): `PluralKit.Core/Models`
- [Model repository](https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Core/Database/Repository/ModelRepository.cs): `PluralKit.Core/Database/Repository/ModelRepository.cs`
- [Postgres database](https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Core/Database/IDatabase.cs): `PluralKit.Core/Database/IDatabase.cs`

### User interfaces

- [HTTP API](https://github.com/pluralkit/pluralkit/tree/main/crates/api/src/endpoints): `crates/api/src/endpoints`
- [Web dashboard](https://github.com/pluralkit/pluralkit/blob/main/dashboard/src/App.svelte): `dashboard/src/App.svelte`

### Supporting services

- [Webhook dispatch](https://github.com/pluralkit/pluralkit/blob/main/PluralKit.Core/Dispatch/DispatchService.cs): `PluralKit.Core/Dispatch/DispatchService.cs`
- [Avatar processing](https://github.com/pluralkit/pluralkit/blob/main/crates/avatars/src/main.rs): `crates/avatars/src/main.rs`
- [Scheduled services](https://github.com/pluralkit/pluralkit/blob/main/crates/scheduled_tasks/src/main.rs): `crates/scheduled_tasks/src/main.rs`

### Other components

- **Discord users**
- **Discord platform**

## Connections

- Discord platform → Gateway shards: sends events (evidence: `README.md`)
- Gateway shards → Shard state: handles packets (evidence: `Myriad/Gateway/State/ShardStateManager.cs`)
- Gateway shards → Bot event router: raises events (evidence: `PluralKit.Bot/Bot.cs`)
- Bot event router → Event handlers: routes events (evidence: `PluralKit.Bot/Bot.cs`)
- Event handlers → Message proxying: handles messages
- Discord users → Bot commands: issues commands
- Bot commands → Model repository: reads and writes (evidence: `PluralKit.Bot/Commands/Member.cs`)
- Bot commands → Profile rendering: renders profiles (evidence: `PluralKit.Bot/Commands/System.cs`)
- Message proxying → Model repository: loads proxy data (evidence: `PluralKit.Bot/Proxy/ProxyService.cs`)
- Message proxying → Webhook dispatch: dispatches updates (evidence: `PluralKit.Bot/Proxy/ProxyService.cs`)
- Message proxying → Discord REST client: relays messages (evidence: `PluralKit.Bot/Proxy/ProxyService.cs`)
- Profile rendering → Discord REST client: fetches Discord data (evidence: `PluralKit.Bot/Services/EmbedService.cs`)
- Profile rendering → Discord cache: fetches cached users (evidence: `PluralKit.Bot/Services/EmbedService.cs`)
- Model repository → Postgres database: queries data (evidence: `PluralKit.Core/Database/Repository/ModelRepository.cs`)
- Model repository → System and member models: loads models
- HTTP API → Postgres database: serves data
- Web dashboard → HTTP API: requests data
- Avatar processing → Postgres database: stores avatar data
- Scheduled services → Postgres database: runs scheduled work
