# pycord-development/pycord architecture

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

- Interactive diagram: https://gitdiagram.com/pycord-development/pycord
- Repository: https://github.com/pycord-development/pycord

## Overview

Pycord is an async Python library for building Discord bots and clients. A bot developer’s application initiates the principal workflow by constructing/configuring a bot and calling `run`; Discord then emits gateway events (messages, interactions, voice state) that Pycord dispatches to the developer’s handlers, whose contexts issue Discord responses or other API operations.

Components

**Application lifecycle and Discord transport**
- **Bot Developer Application and Callbacks** — path: null: Consumer-owned code registers commands and event handlers, as shown by the README’s slash-command and prefix-command examples.
- **Discord Platform** — path: null: The external Discord gateway and HTTP APIs deliver events and receive bot actions.
- **Bot API Facade** — `discord/bot.py`: Provides the documented `discord.Bot` application-facing entry point for declaring application commands and running a bot.
- **Async Client and Dispatcher** — `discord/client.py`: Owns the asyncio loop, listener/task tracking, Discord websocket handle, HTTP client, login lifecycle, and asynchronous event-dispatch machinery.
- **Gateway WebSocket Protocol** — `discord/gateway.py`: Contains the dedicated Discord gateway protocol implementation; receive-loop details were not sampled.
- **REST HTTP Transport** — `discord/http.py`: Implements the HTTP client created by the client runtime for Discord API operations.
- **Connection State and Cache** — `discord/state.py`: Supplies the `ConnectionState` referenced by client-owned channels, interactions, and voice sessions, including access to the loop and HTTP transport.

**Commands, contexts, and interaction responses**
- **Application Command Definitions** — `discord/commands/core.py`: Defines slash, user, and other application-command execution abstractions used by the bot-facing API.
- **Application Interaction Context** — `discord/commands/context.py`: Wraps an `Interaction`, invokes application commands, and delegates `respond`, defer, edit, and original-response operations to it.
- **Prefix Command Definitions** — `discord/ext/commands/core.py`: Provides traditional prefix-command abstractions, including command invocation and help behavior.
- **Prefix Command Context** — `discord/ext/commands/context.py`: Holds parsed command/message state and invokes, reinvokes, replies to, forwards, and renders help for prefix commands.
- **Bridge Command Context** — `discord/ext/bridge/context.py`: Normalizes response, defer, and edit operations across application-interaction and prefix-message command modes.
- **Interaction Resource API** — `discord/interactions.py`: Represents Discord interaction state and response operations consumed by application command contexts.
- **Message Resource API** — `discord/message.py`: Represents Discord messages and supplies reply/forward operations used by prefix command contexts.
- **Async Webhook Interface** — `discord/webhook/async_.py`: Provides webhook and webhook-message interfaces returned or used by interaction-response flows.
- **Interactive UI Kit** — `discord/ui`: Exports views, buttons, selects, modals, layouts, and other Discord message-component helpers.
- **Typing Indicator Context** — `discord/context_managers.py`: Repeatedly calls the channel HTTP typing endpoint every five seconds while its synchronous or async context is active.

**Voice receive and media handling**
- **Voice Client Session** — `discord/voice/client.py`: Validates optional voice dependencies, maintains voice connection/session state and SSRC mappings, handles voice-state updates, and dispatches received voice events to listeners, sinks, and the parent client.
- **Voice Connection State Machine** — `discord/voice/state.py`: Encapsulates voice connection lifecycle state used by the voice client.
- **Voice Packet and Sink Event Routers** — `discord/voice/receive/router.py`: Runs daemon threads that route RTP packets into per-SSRC decoders and queue/register sink event listeners, including child sinks.
- **Opus Packet Decoder** — `discord/opus.py`: Supplies `PacketDecoder` instances used by the receive router to accept RTP packets.
- **Voice Sink Collection** — `discord/sinks/__init__.py`: Exposes official recording/output sinks for PCM and multiple container/audio formats.

Relationships

- **Bot Developer Application and Callbacks -> Bot API Facade:** constructs, decorates, and starts a bot; evidence: README examples call `discord.Bot()`, register commands, and call `run`.
- **Bot API Facade -> Async Client and Dispatcher:** starts/configures the underlying client lifecycle; evidence: the documented `Bot.run` flow, though its implementation was not sampled.
- **Discord Platform -> Gateway WebSocket Protocol:** delivers gateway payloads that drive bot events; evidence: the repository contains a dedicated gateway protocol layer and the client owns a `DiscordWebSocket`.
- **Gateway WebSocket Protocol -> Async Client and Dispatcher:** supplies the client’s websocket transport; evidence: the client stores `self.ws` and exposes event dispatch, while the receive-loop call site was not sampled.
- **Async Client and Dispatcher -> REST HTTP Transport:** constructs and owns an `HTTPClient`; evidence: client initialization instantiates it with connector, proxy, clock, and loop settings.
- **Async Client and Dispatcher -> Bot Developer Application and Callbacks:** schedules dispatched event coroutines as tracked asyncio tasks; evidence: `dispatch` and `_schedule_event` manage callback tasks.
- **Bot API Facade -> Application Command Definitions:** registers application-command callbacks; evidence: README slash and user command decorators.
- **Bot API Facade -> Prefix Command Definitions:** registers prefix-command callbacks; evidence: README `commands.Bot` and `@bot.command()` usage.
- **Application Interaction Context -> Application Command Definitions:** invokes a command callback with itself and supplied arguments; evidence: `invoke` calls `command(self, *args, **kwargs)`.
- **Application Interaction Context -> Interaction Resource API:** delegates response operations; evidence: `respond` calls `interaction.respond` and related methods use the interaction response state.
- **Interaction Resource API -> Discord Platform:** submits interaction responses and follow-up-capable results; evidence: context-facing response methods are defined around the interaction API, though transport internals were not sampled.
- **Prefix Command Context -> Message Resource API:** replies to or forwards the triggering message; evidence: it calls `message.reply` and `message.forward_to`.
- **Bridge Command Context -> Application Interaction Context:** uses inherited application-context response, defer, and edit behavior for interaction commands.
- **Bridge Command Context -> Prefix Command Context:** uses inherited message reply/typing/edit behavior for prefix commands; this is an alternative execution mode, not a sequential stage.
- **Typing Indicator Context -> REST HTTP Transport:** invokes `channel._state.http.send_typing` repeatedly until cancelled.
- **Voice Client Session -> Connection State and Cache:** reads the client connection state and loop and forwards raw voice-state updates into its voice connection state machine.
- **Voice Client Session -> Async Client and Dispatcher:** forwards voice receive events to the parent client after its own listeners and sink dispatch.
- **Voice Packet and Sink Event Routers -> Opus Packet Decoder:** obtains per-SSRC decoders and pushes RTP packets into them.
- **Voice Packet and Sink Event Routers -> Voice Sink Collection:** holds sinks and registers listeners on each sink and its child sinks.

Coverage limits

The sampled excerpts omit the concrete gateway receive loop, HTTP request implementation, command parsing/registration internals, interaction serialization, UI dispatch lifecycle, voice connection handshake, audio decoding output flow, and sink file-writing behavior. Therefore, those components are mapped by documented behavior, dedicated source locations, and visible interfaces rather than asserted as fully traced runtime call chains.

Main entry points: [`discord/client.py`](https://github.com/pycord-development/pycord/blob/master/discord/client.py) (Async Client and Dispatcher), [`discord/bot.py`](https://github.com/pycord-development/pycord/blob/master/discord/bot.py) (Bot API Facade), [`discord/commands/context.py`](https://github.com/pycord-development/pycord/blob/master/discord/commands/context.py) (Application Interaction Context), [`discord/ext/bridge/context.py`](https://github.com/pycord-development/pycord/blob/master/discord/ext/bridge/context.py) (Bridge Command Context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Application Lifecycle"]
  node_developer_app(("Bot Developer Application<br/>external actor"))
  node_discord_platform(("Discord Platform<br/>external platform"))
  node_bot_facade["Bot API Facade<br/>application API"]
  node_async_client["Async Client and Dispatcher<br/>runtime"]
  node_gateway{{"Gateway WebSocket Protocol<br/>[gateway.py]"}}
  node_rest_http["REST HTTP Transport<br/>[http.py]"]
  node_connection_state["Connection State and Cache<br/>[state.py]"]
end

subgraph group_commands["Commands and Responses"]
  node_app_commands["Application Command Definitions<br/>command model"]
  node_interaction_context["Application Interaction Context<br/>command context"]
  node_prefix_commands["Prefix Command Definitions<br/>command model"]
  node_prefix_context["Prefix Command Context<br/>[context.py]"]
  node_bridge_context["Bridge Command Context<br/>[context.py]"]
  node_interaction_api["Interaction Resource API<br/>[interactions.py]"]
  node_message_api["Message Resource API<br/>[message.py]"]
  node_typing_context["Typing Indicator Context<br/>context manager"]
end

subgraph group_voice["Voice and Media"]
  node_voice_client["Voice Client Session<br/>voice runtime"]
  node_voice_state["Voice Connection State Machine<br/>[state.py]"]
  node_voice_router["Voice Packet and Sink Event Routers<br/>[router.py]"]
  node_opus_decoder["Opus Packet Decoder<br/>[opus.py]"]
  node_voice_sinks["Voice Sink Collection<br/>[__init__.py]"]
end

node_developer_app -->|"constructs and runs"| node_bot_facade
node_bot_facade -->|"starts lifecycle"| node_async_client
node_discord_platform -->|"delivers payloads"| node_gateway
node_gateway -->|"supplies websocket"| node_async_client
node_async_client -->|"owns HTTP client"| node_rest_http
node_async_client -->|"schedules callbacks"| node_developer_app
node_bot_facade -->|"registers callbacks"| node_app_commands
node_bot_facade -->|"registers callbacks"| node_prefix_commands
node_interaction_context -->|"invokes command"| node_app_commands
node_interaction_context -->|"delegates responses"| node_interaction_api
node_interaction_api -->|"submits responses"| node_discord_platform
node_prefix_context -->|"replies and forwards"| node_message_api
node_bridge_context -.->|"uses interaction mode"| node_interaction_context
node_bridge_context -.->|"uses prefix mode"| node_prefix_context
node_typing_context -->|"sends typing"| node_rest_http
node_voice_client -->|"forwards voice state"| node_connection_state
node_voice_client -->|"forwards voice events"| node_async_client
node_voice_router -->|"routes RTP packets"| node_opus_decoder
node_voice_router -->|"registers sink listeners"| node_voice_sinks

click node_bot_facade "https://github.com/pycord-development/pycord/blob/master/discord/bot.py"
click node_async_client "https://github.com/pycord-development/pycord/blob/master/discord/client.py"
click node_gateway "https://github.com/pycord-development/pycord/blob/master/discord/gateway.py"
click node_rest_http "https://github.com/pycord-development/pycord/blob/master/discord/http.py"
click node_connection_state "https://github.com/pycord-development/pycord/blob/master/discord/state.py"
click node_app_commands "https://github.com/pycord-development/pycord/blob/master/discord/commands/core.py"
click node_interaction_context "https://github.com/pycord-development/pycord/blob/master/discord/commands/context.py"
click node_prefix_commands "https://github.com/pycord-development/pycord/blob/master/discord/ext/commands/core.py"
click node_prefix_context "https://github.com/pycord-development/pycord/blob/master/discord/ext/commands/context.py"
click node_bridge_context "https://github.com/pycord-development/pycord/blob/master/discord/ext/bridge/context.py"
click node_interaction_api "https://github.com/pycord-development/pycord/blob/master/discord/interactions.py"
click node_message_api "https://github.com/pycord-development/pycord/blob/master/discord/message.py"
click node_typing_context "https://github.com/pycord-development/pycord/blob/master/discord/context_managers.py"
click node_voice_client "https://github.com/pycord-development/pycord/blob/master/discord/voice/client.py"
click node_voice_state "https://github.com/pycord-development/pycord/blob/master/discord/voice/state.py"
click node_voice_router "https://github.com/pycord-development/pycord/blob/master/discord/voice/receive/router.py"
click node_opus_decoder "https://github.com/pycord-development/pycord/blob/master/discord/opus.py"
click node_voice_sinks "https://github.com/pycord-development/pycord/blob/master/discord/sinks/__init__.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_developer_app,node_discord_platform,node_bot_facade,node_async_client,node_gateway,node_rest_http,node_connection_state toneBlue
class node_app_commands,node_interaction_context,node_prefix_commands,node_prefix_context,node_bridge_context,node_interaction_api,node_message_api,node_typing_context toneAmber
class node_voice_client,node_voice_state,node_voice_router,node_opus_decoder,node_voice_sinks toneMint
```

## Components

### Application Lifecycle

- **Bot Developer Application**: external actor · Consumer-owned bot code and callbacks.
- **Discord Platform**: external platform · Discord gateway and HTTP APIs.
- [Bot API Facade](https://github.com/pycord-development/pycord/blob/master/discord/bot.py): application API · `discord/bot.py`
- [Async Client and Dispatcher](https://github.com/pycord-development/pycord/blob/master/discord/client.py): runtime · `discord/client.py`
- [Gateway WebSocket Protocol](https://github.com/pycord-development/pycord/blob/master/discord/gateway.py): protocol · `discord/gateway.py`
- [REST HTTP Transport](https://github.com/pycord-development/pycord/blob/master/discord/http.py): transport · `discord/http.py`
- [Connection State and Cache](https://github.com/pycord-development/pycord/blob/master/discord/state.py): state · `discord/state.py`

### Commands and Responses

- [Application Command Definitions](https://github.com/pycord-development/pycord/blob/master/discord/commands/core.py): command model · `discord/commands/core.py`
- [Application Interaction Context](https://github.com/pycord-development/pycord/blob/master/discord/commands/context.py): command context · `discord/commands/context.py`
- [Prefix Command Definitions](https://github.com/pycord-development/pycord/blob/master/discord/ext/commands/core.py): command model · `discord/ext/commands/core.py`
- [Prefix Command Context](https://github.com/pycord-development/pycord/blob/master/discord/ext/commands/context.py): command context · `discord/ext/commands/context.py`
- [Bridge Command Context](https://github.com/pycord-development/pycord/blob/master/discord/ext/bridge/context.py): command context · `discord/ext/bridge/context.py`
- [Interaction Resource API](https://github.com/pycord-development/pycord/blob/master/discord/interactions.py): resource API · `discord/interactions.py`
- [Message Resource API](https://github.com/pycord-development/pycord/blob/master/discord/message.py): resource API · `discord/message.py`
- [Typing Indicator Context](https://github.com/pycord-development/pycord/blob/master/discord/context_managers.py): context manager · `discord/context_managers.py`

### Voice and Media

- [Voice Client Session](https://github.com/pycord-development/pycord/blob/master/discord/voice/client.py): voice runtime · `discord/voice/client.py`
- [Voice Connection State Machine](https://github.com/pycord-development/pycord/blob/master/discord/voice/state.py): state machine · `discord/voice/state.py`
- [Voice Packet and Sink Event Routers](https://github.com/pycord-development/pycord/blob/master/discord/voice/receive/router.py): event router · `discord/voice/receive/router.py`
- [Opus Packet Decoder](https://github.com/pycord-development/pycord/blob/master/discord/opus.py): decoder · `discord/opus.py`
- [Voice Sink Collection](https://github.com/pycord-development/pycord/blob/master/discord/sinks/__init__.py): sink collection · `discord/sinks/__init__.py`

## Connections

- Bot Developer Application → Bot API Facade: constructs and runs
- Bot API Facade → Async Client and Dispatcher: starts lifecycle
- Discord Platform → Gateway WebSocket Protocol: delivers payloads
- Gateway WebSocket Protocol → Async Client and Dispatcher: supplies websocket
- Async Client and Dispatcher → REST HTTP Transport: owns HTTP client
- Async Client and Dispatcher → Bot Developer Application: schedules callbacks
- Bot API Facade → Application Command Definitions: registers callbacks
- Bot API Facade → Prefix Command Definitions: registers callbacks
- Application Interaction Context → Application Command Definitions: invokes command
- Application Interaction Context → Interaction Resource API: delegates responses
- Interaction Resource API → Discord Platform: submits responses
- Prefix Command Context → Message Resource API: replies and forwards
- Bridge Command Context → Application Interaction Context: uses interaction mode · Alternative execution mode.
- Bridge Command Context → Prefix Command Context: uses prefix mode · Alternative execution mode.
- Typing Indicator Context → REST HTTP Transport: sends typing
- Voice Client Session → Connection State and Cache: forwards voice state
- Voice Client Session → Async Client and Dispatcher: forwards voice events
- Voice Packet and Sink Event Routers → Opus Packet Decoder: routes RTP packets
- Voice Packet and Sink Event Routers → Voice Sink Collection: registers sink listeners
