# wangk-ask/wecom-reader architecture

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

- Interactive diagram: https://gitdiagram.com/wangk-ask/wecom-reader
- Repository: https://github.com/wangk-ask/wecom-reader

## Overview

wecom-reader extracts a key from the running WeCom client, decrypts local databases, then exposes conversation, message, search, contact and export workflows through a Python API, CLI and Web UI. The graph separates acquisition/decryption from SQLite-backed domain queries and user interfaces. The excerpts show the key verification and query implementations, and explicit UI-to-reader calls; some reader internals are omitted, so only relationships established by the index or README are shown. MCP, export and parser directories contain no sampled runtime implementation.

Main entry points: [`wecom_reader/reader.py`](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/reader.py) (WeComReader API), [`wecom_reader/crypto/key_extract.py`](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/crypto/key_extract.py) (Key Extraction), [`wecom_reader/crypto/decrypt.py`](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/crypto/decrypt.py) (AES Decryption), [`wecom_reader/cli.py`](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Key and Decryption"]
  node_extract["Key Extraction<br/>[key_extract.py]"]
  node_decrypt["AES Decryption<br/>[decrypt.py]"]
end

subgraph group_queries["Local Data Queries"]
  node_sessions["Session Queries<br/>[session.py]"]
  node_messages["Message Queries<br/>[message.py]"]
  node_contacts["Contact Queries<br/>[contact.py]"]
end

subgraph group_api["Reader API"]
  node_reader["WeComReader API<br/>[reader.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_web["Web UI and API<br/>[web.py]"]
end

node_operator(("User"))
node_wxwork(("WXWork.exe"))
node_encrypted[("Encrypted Databases")]
node_decrypted[("Decrypted Databases")]

node_wxwork -->|"provides memory"| node_extract
node_encrypted -->|"scans databases"| node_extract
node_extract -->|"verifies keys"| node_decrypt
node_operator -->|"initializes"| node_reader
node_reader -->|"extracts keys"| node_extract
node_reader -->|"decrypts databases"| node_decrypt
node_encrypted -->|"input pages"| node_decrypt
node_decrypt -->|"writes databases"| node_decrypted
node_decrypted -->|"session queries"| node_sessions
node_decrypted -->|"message queries"| node_messages
node_decrypted -->|"contact queries"| node_contacts
node_reader -->|"queries sessions"| node_sessions
node_reader -->|"queries messages"| node_messages
node_reader -->|"queries contacts"| node_contacts
node_operator -->|"runs commands"| node_cli
node_cli -->|"calls API"| node_reader
node_operator -->|"uses browser"| node_web
node_web -->|"calls API"| node_reader

click node_extract "https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/crypto/key_extract.py"
click node_decrypt "https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/crypto/decrypt.py"
click node_sessions "https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/db/session.py"
click node_messages "https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/db/message.py"
click node_contacts "https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/db/contact.py"
click node_reader "https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/reader.py"
click node_cli "https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/cli.py"
click node_web "https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/web.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_extract,node_decrypt,node_operator toneBlue
class node_sessions,node_messages,node_contacts,node_encrypted,node_decrypted toneAmber
class node_reader toneMint
class node_cli,node_web toneRose
class node_wxwork toneIndigo
```

## Components

### Key and Decryption

- [Key Extraction](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/crypto/key_extract.py): `wecom_reader/crypto/key_extract.py`
- [AES Decryption](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/crypto/decrypt.py): `wecom_reader/crypto/decrypt.py`

### Local Data Queries

- [Session Queries](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/db/session.py): `wecom_reader/db/session.py`
- [Message Queries](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/db/message.py): `wecom_reader/db/message.py`
- [Contact Queries](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/db/contact.py): `wecom_reader/db/contact.py`

### Reader API

- [WeComReader API](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/reader.py): `wecom_reader/reader.py`

### User Interfaces

- [CLI](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/cli.py): `wecom_reader/cli.py`
- [Web UI and API](https://github.com/wangk-ask/wecom-reader/blob/feat/initial-release/wecom_reader/web.py): `wecom_reader/web.py`

### Other components

- **User**
- **WXWork.exe**
- **Encrypted Databases**
- **Decrypted Databases**

## Connections

- WXWork.exe → Key Extraction: provides memory (evidence: `README.md`)
- Encrypted Databases → Key Extraction: scans databases (evidence: `wecom_reader/crypto/key_extract.py`)
- Key Extraction → AES Decryption: verifies keys (evidence: `wecom_reader/crypto/key_extract.py`)
- User → WeComReader API: initializes (evidence: `README.md`)
- WeComReader API → Key Extraction: extracts keys (evidence: `README.md`)
- WeComReader API → AES Decryption: decrypts databases (evidence: `README.md`)
- Encrypted Databases → AES Decryption: input pages (evidence: `README.md`)
- AES Decryption → Decrypted Databases: writes databases (evidence: `README.md`)
- Decrypted Databases → Session Queries: session queries (evidence: `wecom_reader/db/session.py`)
- Decrypted Databases → Message Queries: message queries (evidence: `wecom_reader/db/message.py`)
- Decrypted Databases → Contact Queries: contact queries (evidence: `wecom_reader/db/contact.py`)
- WeComReader API → Session Queries: queries sessions (evidence: `wecom_reader/reader.py`)
- WeComReader API → Message Queries: queries messages (evidence: `wecom_reader/reader.py`)
- WeComReader API → Contact Queries: queries contacts (evidence: `wecom_reader/reader.py`)
- User → CLI: runs commands (evidence: `wecom_reader/cli.py`)
- CLI → WeComReader API: calls API (evidence: `wecom_reader/cli.py`)
- User → Web UI and API: uses browser (evidence: `README.md`)
- Web UI and API → WeComReader API: calls API (evidence: `wecom_reader/web.py`)
