# littlecodersh/itchat architecture

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

- Interactive diagram: https://gitdiagram.com/littlecodersh/itchat
- Repository: https://github.com/littlecodersh/itchat

## Overview

itchat is a Python client library for operating a personal WeChat account: users log in, register message handlers, run a receive loop, and can send replies or perform contact and chatroom operations. The map also includes login-state persistence, message/file handling, contact and session state, and the library’s user-facing value models. Source excerpts are partial, so some documented capabilities are shown without inferred internal call chains; dashed links mark relationships whose implementation was not verified.

Main entry points: [`itchat/components/messages.py`](https://github.com/littlecodersh/itchat/blob/master/itchat/components/messages.py) (Message operations), [`itchat/core.py`](https://github.com/littlecodersh/itchat/blob/master/itchat/core.py) (Core client), [`itchat/components/contact.py`](https://github.com/littlecodersh/itchat/blob/master/itchat/components/contact.py) (Contacts and chats), [`itchat/storage/__init__.py`](https://github.com/littlecodersh/itchat/blob/master/itchat/storage/__init__.py) (Client state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_api["itchat API<br/>[__init__.py]"]
  node_core["Core client<br/>[core.py]"]
end

subgraph group_account["Account and Contacts"]
  node_login["Login and sync<br/>[login.py]"]
  node_hotreload["Session persistence<br/>[hotreload.py]"]
  node_contacts["Contacts and chats<br/>[contact.py]"]
end

subgraph group_messaging["Messaging"]
  node_register["Handler registration<br/>[register.py]"]
  node_messages["Message operations<br/>[messages.py]"]
  node_content["Message types<br/>[content.py]"]
end

subgraph group_runtime_state["Runtime State"]
  node_storage[("Client state<br/>[__init__.py]")]
  node_queue["Message queue<br/>[messagequeue.py]"]
  node_models["User and chat models<br/>[templates.py]"]
  node_results["API results<br/>[returnvalues.py]"]
  node_config["Client configuration<br/>[config.py]"]
  node_utils["Protocol utilities<br/>[utils.py]"]
  node_logging["Logging<br/>[log.py]"]
end

node_user(("Application developer"))
node_wechat(("WeChat service"))

node_user -->|"calls"| node_api
node_api -->|"creates client"| node_core
node_core -->|"delegates login"| node_login
node_core -->|"delegates contacts"| node_contacts
node_core -->|"delegates messaging"| node_messages
node_core -->|"delegates handlers"| node_register
node_login -->|"authenticates and syncs"| node_wechat
node_login -->|"updates session state"| node_storage
node_login -->|"uses contact updates"| node_contacts
node_hotreload -->|"saves and restores"| node_storage
node_hotreload -->|"queues recovered messages"| node_messages
node_contacts -->|"fetches and changes contacts"| node_wechat
node_contacts -->|"updates local contacts"| node_storage
node_messages -->|"sends and downloads"| node_wechat
node_messages -->|"looks up chat state"| node_storage
node_register -->|"accepts callbacks"| node_user
node_register -.->|"dispatches handlers"| node_messages
node_api -->|"exposes types"| node_content
node_storage -->|"holds messages"| node_queue
node_storage -->|"builds contact models"| node_models
node_models -->|"delegates user actions"| node_core
node_messages -->|"returns status"| node_results
node_contacts -->|"returns status"| node_results
node_login -->|"uses settings"| node_config
node_messages -->|"uses settings"| node_config
node_contacts -->|"formats and searches"| node_utils
node_register -->|"uses helpers"| node_utils
node_api -->|"exposes logging"| node_logging

click node_api "https://github.com/littlecodersh/itchat/blob/master/itchat/__init__.py"
click node_core "https://github.com/littlecodersh/itchat/blob/master/itchat/core.py"
click node_login "https://github.com/littlecodersh/itchat/blob/master/itchat/components/login.py"
click node_hotreload "https://github.com/littlecodersh/itchat/blob/master/itchat/components/hotreload.py"
click node_contacts "https://github.com/littlecodersh/itchat/blob/master/itchat/components/contact.py"
click node_register "https://github.com/littlecodersh/itchat/blob/master/itchat/components/register.py"
click node_messages "https://github.com/littlecodersh/itchat/blob/master/itchat/components/messages.py"
click node_content "https://github.com/littlecodersh/itchat/blob/master/itchat/content.py"
click node_storage "https://github.com/littlecodersh/itchat/blob/master/itchat/storage/__init__.py"
click node_queue "https://github.com/littlecodersh/itchat/blob/master/itchat/storage/messagequeue.py"
click node_models "https://github.com/littlecodersh/itchat/blob/master/itchat/storage/templates.py"
click node_results "https://github.com/littlecodersh/itchat/blob/master/itchat/returnvalues.py"
click node_config "https://github.com/littlecodersh/itchat/blob/master/itchat/config.py"
click node_utils "https://github.com/littlecodersh/itchat/blob/master/itchat/utils.py"
click node_logging "https://github.com/littlecodersh/itchat/blob/master/itchat/log.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_api,node_core toneBlue
class node_login,node_hotreload,node_contacts toneAmber
class node_register,node_messages,node_content toneMint
class node_storage,node_queue,node_models,node_results,node_config,node_utils,node_logging toneRose
class node_user,node_wechat toneIndigo
```

## Components

### Public API

- [itchat API](https://github.com/littlecodersh/itchat/blob/master/itchat/__init__.py): `itchat/__init__.py`
- [Core client](https://github.com/littlecodersh/itchat/blob/master/itchat/core.py): `itchat/core.py`

### Account and Contacts

- [Login and sync](https://github.com/littlecodersh/itchat/blob/master/itchat/components/login.py): `itchat/components/login.py`
- [Session persistence](https://github.com/littlecodersh/itchat/blob/master/itchat/components/hotreload.py): `itchat/components/hotreload.py`
- [Contacts and chats](https://github.com/littlecodersh/itchat/blob/master/itchat/components/contact.py): `itchat/components/contact.py`

### Messaging

- [Handler registration](https://github.com/littlecodersh/itchat/blob/master/itchat/components/register.py): `itchat/components/register.py`
- [Message operations](https://github.com/littlecodersh/itchat/blob/master/itchat/components/messages.py): `itchat/components/messages.py`
- [Message types](https://github.com/littlecodersh/itchat/blob/master/itchat/content.py): `itchat/content.py`

### Runtime State

- [Client state](https://github.com/littlecodersh/itchat/blob/master/itchat/storage/__init__.py): `itchat/storage/__init__.py`
- [Message queue](https://github.com/littlecodersh/itchat/blob/master/itchat/storage/messagequeue.py): `itchat/storage/messagequeue.py`
- [User and chat models](https://github.com/littlecodersh/itchat/blob/master/itchat/storage/templates.py): `itchat/storage/templates.py`
- [API results](https://github.com/littlecodersh/itchat/blob/master/itchat/returnvalues.py): `itchat/returnvalues.py`
- [Client configuration](https://github.com/littlecodersh/itchat/blob/master/itchat/config.py): `itchat/config.py`
- [Protocol utilities](https://github.com/littlecodersh/itchat/blob/master/itchat/utils.py): `itchat/utils.py`
- [Logging](https://github.com/littlecodersh/itchat/blob/master/itchat/log.py): `itchat/log.py`

### Other components

- **Application developer**
- **WeChat service**

## Connections

- Application developer → itchat API: calls (evidence: `README.md`)
- itchat API → Core client: creates client (evidence: `itchat/__init__.py`)
- Core client → Login and sync: delegates login (evidence: `itchat/core.py`)
- Core client → Contacts and chats: delegates contacts (evidence: `itchat/core.py`)
- Core client → Message operations: delegates messaging (evidence: `itchat/core.py`)
- Core client → Handler registration: delegates handlers
- Login and sync → WeChat service: authenticates and syncs (evidence: `itchat/components/login.py`)
- Login and sync → Client state: updates session state (evidence: `itchat/components/login.py`)
- Login and sync → Contacts and chats: uses contact updates (evidence: `itchat/components/login.py`)
- Session persistence → Client state: saves and restores (evidence: `itchat/components/hotreload.py`)
- Session persistence → Message operations: queues recovered messages (evidence: `itchat/components/hotreload.py`)
- Contacts and chats → WeChat service: fetches and changes contacts (evidence: `itchat/components/contact.py`)
- Contacts and chats → Client state: updates local contacts (evidence: `itchat/components/contact.py`)
- Message operations → WeChat service: sends and downloads (evidence: `itchat/components/messages.py`)
- Message operations → Client state: looks up chat state (evidence: `itchat/components/messages.py`)
- Handler registration → Application developer: accepts callbacks (evidence: `README.md`)
- Handler registration → Message operations: dispatches handlers
- itchat API → Message types: exposes types (evidence: `itchat/__init__.py`)
- Client state → Message queue: holds messages (evidence: `itchat/storage/__init__.py`)
- Client state → User and chat models: builds contact models (evidence: `itchat/storage/__init__.py`)
- User and chat models → Core client: delegates user actions (evidence: `itchat/storage/templates.py`)
- Message operations → API results: returns status (evidence: `itchat/components/messages.py`)
- Contacts and chats → API results: returns status (evidence: `itchat/components/contact.py`)
- Login and sync → Client configuration: uses settings (evidence: `itchat/components/login.py`)
- Message operations → Client configuration: uses settings (evidence: `itchat/components/messages.py`)
- Contacts and chats → Protocol utilities: formats and searches (evidence: `itchat/components/contact.py`)
- Handler registration → Protocol utilities: uses helpers (evidence: `itchat/components/register.py`)
- itchat API → Logging: exposes logging (evidence: `itchat/__init__.py`)
