# tencent-connect/botpy architecture

> Architecture diagram of the GitHub repository tencent-connect/botpy, 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/tencent-connect/botpy
- Repository: https://github.com/tencent-connect/botpy

## Overview

botpy is an asynchronous Python SDK for QQ bot platform APIs. The primary workflow is: an application configures event intents and starts Client; the client establishes gateway sessions, incoming events are parsed into domain objects and dispatched to application handlers, which can invoke BotAPI methods that issue authenticated HTTP requests. The SDK also exposes channel, guild, forum, interaction, audio, user, reaction, and management capabilities. The source excerpts establish the main gateway and HTTP calls; some subsystem links are README-backed or omitted where their caller was not sampled.

Main entry points: [`botpy/connection.py`](https://github.com/tencent-connect/botpy/blob/master/botpy/connection.py) (Event Parsing), [`botpy/client.py`](https://github.com/tencent-connect/botpy/blob/master/botpy/client.py) (Client Lifecycle), [`botpy/api.py`](https://github.com/tencent-connect/botpy/blob/master/botpy/api.py) (Bot API), [`botpy/http.py`](https://github.com/tencent-connect/botpy/blob/master/botpy/http.py) (HTTP Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Client Runtime"]
  node_client["Client Lifecycle<br/>[client.py]"]
  node_intents["Event Intents<br/>[flags.py]"]
  node_session["Shard Session<br/>[session.py]"]
end

subgraph group_gateway["Gateway Events"]
  node_gateway_ws["Gateway Transport<br/>[gateway.py]"]
  node_event_router["Event Parsing<br/>[connection.py]"]
end

subgraph group_rest["Platform API"]
  node_bot_api["Bot API<br/>[api.py]"]
  node_http["HTTP Client<br/>[http.py]"]
end

subgraph group_domain["Domain Models"]
  node_message_models["Message Events<br/>[message.py]"]
  node_guild_events["Guild Events<br/>[guild.py]"]
  node_channel_events["Channel Events<br/>[channel.py]"]
  node_forum_events["Forum Events<br/>[forum.py]"]
  node_interaction_events["Interaction Events<br/>[interaction.py]"]
  node_audio_events["Audio Events<br/>[audio.py]"]
  node_reaction_events["Reaction Events<br/>[reaction.py]"]
  node_management_events["Management Events<br/>[manage.py]"]
  node_payload_types["API Payload Types"]
end

subgraph group_support["Runtime Support"]
  node_token["Token Auth<br/>[robot.py]"]
  node_logging["Logging<br/>[logging.py]"]
  node_extensions["SDK Extensions"]
end

node_app(("Bot Application"))
node_qq_platform(("QQ Bot Platform"))

node_app -->|"starts"| node_client
node_app -->|"configures"| node_intents
node_client -->|"uses"| node_intents
node_client -->|"creates"| node_bot_api
node_client -->|"starts sessions"| node_gateway_ws
node_client -->|"builds shards"| node_session
node_gateway_ws -->|"delivers events"| node_event_router
node_event_router -->|"constructs messages"| node_message_models
node_event_router -->|"constructs events"| node_guild_events
node_event_router -->|"constructs events"| node_channel_events
node_event_router -->|"constructs events"| node_forum_events
node_event_router -->|"constructs events"| node_interaction_events
node_event_router -->|"constructs events"| node_audio_events
node_event_router -->|"constructs events"| node_reaction_events
node_event_router -->|"constructs events"| node_management_events
node_event_router -->|"dispatches handlers"| node_client
node_client -->|"dispatches callbacks"| node_app
node_app -->|"invokes endpoints"| node_bot_api
node_message_models -->|"replies via"| node_bot_api
node_bot_api -->|"sends requests"| node_http
node_http -->|"HTTP requests"| node_qq_platform
node_http -->|"uses credentials"| node_token
node_token -->|"fetches access token"| node_qq_platform
node_bot_api -->|"uses schemas"| node_payload_types
node_client -->|"configures"| node_logging
node_http -->|"logs requests"| node_logging
node_app -.->|"may use"| node_extensions

click node_client "https://github.com/tencent-connect/botpy/blob/master/botpy/client.py"
click node_intents "https://github.com/tencent-connect/botpy/blob/master/botpy/flags.py"
click node_session "https://github.com/tencent-connect/botpy/blob/master/botpy/types/session.py"
click node_gateway_ws "https://github.com/tencent-connect/botpy/blob/master/botpy/gateway.py"
click node_event_router "https://github.com/tencent-connect/botpy/blob/master/botpy/connection.py"
click node_message_models "https://github.com/tencent-connect/botpy/blob/master/botpy/message.py"
click node_guild_events "https://github.com/tencent-connect/botpy/blob/master/botpy/guild.py"
click node_channel_events "https://github.com/tencent-connect/botpy/blob/master/botpy/channel.py"
click node_forum_events "https://github.com/tencent-connect/botpy/blob/master/botpy/forum.py"
click node_interaction_events "https://github.com/tencent-connect/botpy/blob/master/botpy/interaction.py"
click node_audio_events "https://github.com/tencent-connect/botpy/blob/master/botpy/audio.py"
click node_reaction_events "https://github.com/tencent-connect/botpy/blob/master/botpy/reaction.py"
click node_management_events "https://github.com/tencent-connect/botpy/blob/master/botpy/manage.py"
click node_bot_api "https://github.com/tencent-connect/botpy/blob/master/botpy/api.py"
click node_http "https://github.com/tencent-connect/botpy/blob/master/botpy/http.py"
click node_token "https://github.com/tencent-connect/botpy/blob/master/botpy/robot.py"
click node_logging "https://github.com/tencent-connect/botpy/blob/master/botpy/logging.py"
click node_payload_types "https://github.com/tencent-connect/botpy/tree/master/botpy/types"
click node_extensions "https://github.com/tencent-connect/botpy/tree/master/botpy/ext"

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_client,node_intents,node_session toneBlue
class node_gateway_ws,node_event_router toneAmber
class node_bot_api,node_http toneMint
class node_message_models,node_guild_events,node_channel_events,node_forum_events,node_interaction_events,node_audio_events,node_reaction_events,node_management_events,node_payload_types toneRose
class node_token,node_logging,node_extensions,node_app,node_qq_platform toneIndigo
```

## Components

### Client Runtime

- [Client Lifecycle](https://github.com/tencent-connect/botpy/blob/master/botpy/client.py): `botpy/client.py`
- [Event Intents](https://github.com/tencent-connect/botpy/blob/master/botpy/flags.py): `botpy/flags.py`
- [Shard Session](https://github.com/tencent-connect/botpy/blob/master/botpy/types/session.py): `botpy/types/session.py`

### Gateway Events

- [Gateway Transport](https://github.com/tencent-connect/botpy/blob/master/botpy/gateway.py): `botpy/gateway.py`
- [Event Parsing](https://github.com/tencent-connect/botpy/blob/master/botpy/connection.py): `botpy/connection.py`

### Platform API

- [Bot API](https://github.com/tencent-connect/botpy/blob/master/botpy/api.py): `botpy/api.py`
- [HTTP Client](https://github.com/tencent-connect/botpy/blob/master/botpy/http.py): `botpy/http.py`

### Domain Models

- [Message Events](https://github.com/tencent-connect/botpy/blob/master/botpy/message.py): `botpy/message.py`
- [Guild Events](https://github.com/tencent-connect/botpy/blob/master/botpy/guild.py): `botpy/guild.py`
- [Channel Events](https://github.com/tencent-connect/botpy/blob/master/botpy/channel.py): `botpy/channel.py`
- [Forum Events](https://github.com/tencent-connect/botpy/blob/master/botpy/forum.py): `botpy/forum.py`
- [Interaction Events](https://github.com/tencent-connect/botpy/blob/master/botpy/interaction.py): `botpy/interaction.py`
- [Audio Events](https://github.com/tencent-connect/botpy/blob/master/botpy/audio.py): `botpy/audio.py`
- [Reaction Events](https://github.com/tencent-connect/botpy/blob/master/botpy/reaction.py): `botpy/reaction.py`
- [Management Events](https://github.com/tencent-connect/botpy/blob/master/botpy/manage.py): `botpy/manage.py`
- [API Payload Types](https://github.com/tencent-connect/botpy/tree/master/botpy/types): `botpy/types`

### Runtime Support

- [Token Auth](https://github.com/tencent-connect/botpy/blob/master/botpy/robot.py): `botpy/robot.py`
- [Logging](https://github.com/tencent-connect/botpy/blob/master/botpy/logging.py): `botpy/logging.py`
- [SDK Extensions](https://github.com/tencent-connect/botpy/tree/master/botpy/ext): `botpy/ext`

### Other components

- **Bot Application**
- **QQ Bot Platform**

## Connections

- Bot Application → Client Lifecycle: starts (evidence: `README.md`)
- Bot Application → Event Intents: configures (evidence: `README.md`)
- Client Lifecycle → Event Intents: uses (evidence: `botpy/client.py`)
- Client Lifecycle → Bot API: creates (evidence: `botpy/client.py`)
- Client Lifecycle → Gateway Transport: starts sessions (evidence: `botpy/client.py`)
- Client Lifecycle → Shard Session: builds shards (evidence: `botpy/client.py`)
- Gateway Transport → Event Parsing: delivers events (evidence: `botpy/gateway.py`)
- Event Parsing → Message Events: constructs messages (evidence: `botpy/connection.py`)
- Event Parsing → Guild Events: constructs events (evidence: `botpy/connection.py`)
- Event Parsing → Channel Events: constructs events (evidence: `botpy/connection.py`)
- Event Parsing → Forum Events: constructs events (evidence: `botpy/connection.py`)
- Event Parsing → Interaction Events: constructs events (evidence: `botpy/connection.py`)
- Event Parsing → Audio Events: constructs events (evidence: `botpy/connection.py`)
- Event Parsing → Reaction Events: constructs events (evidence: `botpy/connection.py`)
- Event Parsing → Management Events: constructs events (evidence: `botpy/connection.py`)
- Event Parsing → Client Lifecycle: dispatches handlers (evidence: `botpy/connection.py`)
- Client Lifecycle → Bot Application: dispatches callbacks (evidence: `botpy/client.py`)
- Bot Application → Bot API: invokes endpoints (evidence: `README.md`)
- Message Events → Bot API: replies via (evidence: `botpy/message.py`)
- Bot API → HTTP Client: sends requests (evidence: `botpy/api.py`)
- HTTP Client → QQ Bot Platform: HTTP requests (evidence: `botpy/http.py`)
- HTTP Client → Token Auth: uses credentials (evidence: `botpy/http.py`)
- Token Auth → QQ Bot Platform: fetches access token (evidence: `botpy/robot.py`)
- Bot API → API Payload Types: uses schemas (evidence: `botpy/api.py`)
- Client Lifecycle → Logging: configures (evidence: `botpy/client.py`)
- HTTP Client → Logging: logs requests (evidence: `botpy/http.py`)
- Bot Application → SDK Extensions: may use