# harcicyang/hiro-qq architecture

> Architecture diagram of the GitHub repository harcicyang/hiro-qq, 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/harcicyang/hiro-qq
- Repository: https://github.com/harcicyang/hiro-qq

## Overview

Hiro QQ is a Python implementation of the NTQQ PC protocol. Its main workflow is to configure device, app, and session information; register and authenticate a client; exchange protocol packets; then send messages or receive server pushes that become typed events. The repository also includes friend/group operations, rich-message and media handling, and file transfers. The graph reflects documented features and relationships visible in the supplied excerpts or SOURCE INDEX; several subsystem internals are unsampled, so their detailed call paths are omitted.

Main entry points: [`lagrange/client/client.py`](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/client.py) (Client API), [`lagrange/client/base.py`](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/base.py) (Base client), [`lagrange/client/message/decoder.py`](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/message/decoder.py) (Message decoder), [`lagrange/pb/message/rich_text/elems.py`](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/pb/message/rich_text/elems.py) (Message protocol models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_session["Session and transport"]
  node_client["Client API<br/>[client.py]"]
  node_base["Base client<br/>[base.py]"]
  node_login["WTLogin<br/>[sso.py]"]
  node_pushsvc["Push service<br/>[service.py]"]
  node_network["Network transport<br/>[network.py]"]
  node_packet["Packet handling<br/>[packet.py]"]
  node_info["Device and session info<br/>[__init__.py]"]
end

subgraph group_messages["Messaging and events"]
  node_events["Event dispatch<br/>[event.py]"]
  node_friend["Friend events<br/>[friend.py]"]
  node_group["Group events<br/>[group.py]"]
  node_pushmsg["Incoming message pushes<br/>[msg.py]"]
  node_decoder["Message decoder<br/>[decoder.py]"]
  node_encoder["Message encoder<br/>[encoder.py]"]
  node_elements["Message elements<br/>[elems.py]"]
  node_messagepb["Message protocol models<br/>[elems.py]"]
end

subgraph group_media["Media transfer"]
  node_highway["Highway transfers<br/>[highway.py]"]
  node_filepb["File service models<br/>[file.py]"]
end

subgraph group_protocol["Protocol foundations"]
  node_protobuf["Protobuf codec<br/>[coder.py]"]
  node_reader["Binary reader<br/>[reader.py]"]
  node_serial["Info serialization<br/>[serialize.py]"]
end

node_user(("Application"))

node_user -->|"uses"| node_client
node_client -->|"inherits"| node_base
node_client -->|"binds pushes"| node_pushsvc
node_client -->|"uploads files"| node_highway
node_client -->|"builds messages"| node_encoder
node_client -->|"uses message models"| node_messagepb
node_client -->|"uses session info"| node_info
node_base -->|"performs login"| node_login
node_base -->|"uses transport"| node_network
node_base -->|"handles packets"| node_packet
node_pushsvc -->|"emits events"| node_events
node_pushmsg -->|"decodes pushes"| node_decoder
node_decoder -->|"creates friend events"| node_friend
node_decoder -->|"creates group events"| node_group
node_decoder -->|"reads message models"| node_messagepb
node_encoder -->|"encodes elements"| node_elements
node_encoder -->|"builds protocol data"| node_messagepb
node_elements -->|"builds quotes"| node_group
node_highway -->|"uses file models"| node_filepb
node_highway -->|"uses media models"| node_messagepb
node_protobuf -->|"decodes bytes"| node_reader
node_serial -->|"reads binary data"| node_reader
node_serial -.->|"serializes info"| node_protobuf

click node_client "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/client.py"
click node_base "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/base.py"
click node_login "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/wtlogin/sso.py"
click node_pushsvc "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/server_push/service.py"
click node_network "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/network.py"
click node_packet "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/packet.py"
click node_info "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/info/__init__.py"
click node_events "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/event.py"
click node_friend "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/events/friend.py"
click node_group "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/events/group.py"
click node_pushmsg "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/server_push/msg.py"
click node_decoder "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/message/decoder.py"
click node_encoder "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/message/encoder.py"
click node_elements "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/message/elems.py"
click node_messagepb "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/pb/message/rich_text/elems.py"
click node_highway "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/highway/highway.py"
click node_filepb "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/pb/service/file.py"
click node_protobuf "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/utils/binary/protobuf/coder.py"
click node_reader "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/utils/binary/reader.py"
click node_serial "https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/info/serialize.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_client,node_base,node_login,node_pushsvc,node_network,node_packet,node_info toneBlue
class node_events,node_friend,node_group,node_pushmsg,node_decoder,node_encoder,node_elements,node_messagepb toneAmber
class node_highway,node_filepb toneMint
class node_protobuf,node_reader,node_serial toneRose
class node_user toneIndigo
```

## Components

### Session and transport

- [Client API](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/client.py): `lagrange/client/client.py`
- [Base client](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/base.py): `lagrange/client/base.py`
- [WTLogin](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/wtlogin/sso.py): `lagrange/client/wtlogin/sso.py`
- [Push service](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/server_push/service.py): `lagrange/client/server_push/service.py`
- [Network transport](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/network.py): `lagrange/client/network.py`
- [Packet handling](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/packet.py): `lagrange/client/packet.py`
- [Device and session info](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/info/__init__.py): `lagrange/info/__init__.py`

### Messaging and events

- [Event dispatch](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/event.py): `lagrange/client/event.py`
- [Friend events](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/events/friend.py): `lagrange/client/events/friend.py`
- [Group events](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/events/group.py): `lagrange/client/events/group.py`
- [Incoming message pushes](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/server_push/msg.py): `lagrange/client/server_push/msg.py`
- [Message decoder](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/message/decoder.py): `lagrange/client/message/decoder.py`
- [Message encoder](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/message/encoder.py): `lagrange/client/message/encoder.py`
- [Message elements](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/message/elems.py): `lagrange/client/message/elems.py`
- [Message protocol models](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/pb/message/rich_text/elems.py): `lagrange/pb/message/rich_text/elems.py`

### Media transfer

- [Highway transfers](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/client/highway/highway.py): `lagrange/client/highway/highway.py`
- [File service models](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/pb/service/file.py): `lagrange/pb/service/file.py`

### Protocol foundations

- [Protobuf codec](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/utils/binary/protobuf/coder.py): `lagrange/utils/binary/protobuf/coder.py`
- [Binary reader](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/utils/binary/reader.py): `lagrange/utils/binary/reader.py`
- [Info serialization](https://github.com/harcicyang/hiro-qq/blob/broken/lagrange/info/serialize.py): `lagrange/info/serialize.py`

### Other components

- **Application**

## Connections

- Application → Client API: uses (evidence: `lagrange/client/client.py`)
- Client API → Base client: inherits (evidence: `lagrange/client/client.py`)
- Client API → Push service: binds pushes (evidence: `lagrange/client/client.py`)
- Client API → Highway transfers: uploads files (evidence: `lagrange/client/client.py`)
- Client API → Message encoder: builds messages (evidence: `lagrange/client/client.py`)
- Client API → Message protocol models: uses message models (evidence: `lagrange/client/client.py`)
- Client API → Device and session info: uses session info (evidence: `lagrange/__init__.py`)
- Base client → WTLogin: performs login (evidence: `lagrange/client/base.py`)
- Base client → Network transport: uses transport (evidence: `lagrange/client/base.py`)
- Base client → Packet handling: handles packets (evidence: `lagrange/client/base.py`)
- Push service → Event dispatch: emits events (evidence: `lagrange/client/server_push/service.py`)
- Incoming message pushes → Message decoder: decodes pushes (evidence: `lagrange/client/message/decoder.py`)
- Message decoder → Friend events: creates friend events (evidence: `lagrange/client/message/decoder.py`)
- Message decoder → Group events: creates group events (evidence: `lagrange/client/message/decoder.py`)
- Message decoder → Message protocol models: reads message models (evidence: `lagrange/client/message/decoder.py`)
- Message encoder → Message elements: encodes elements (evidence: `lagrange/client/message/encoder.py`)
- Message encoder → Message protocol models: builds protocol data (evidence: `lagrange/client/message/encoder.py`)
- Message elements → Group events: builds quotes (evidence: `lagrange/client/message/elems.py`)
- Highway transfers → File service models: uses file models (evidence: `lagrange/client/highway/highway.py`)
- Highway transfers → Message protocol models: uses media models (evidence: `lagrange/client/highway/highway.py`)
- Protobuf codec → Binary reader: decodes bytes (evidence: `lagrange/utils/binary/protobuf/coder.py`)
- Info serialization → Binary reader: reads binary data (evidence: `lagrange/info/serialize.py`)
- Info serialization → Protobuf codec: serializes info