# hello-mr-crab/pywechat architecture

> Architecture diagram of the GitHub repository hello-mr-crab/pywechat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hello-mr-crab/pywechat
- Repository: https://github.com/hello-mr-crab/pywechat

## Overview

##### Project Type and Purpose
- This is an open-source, Windows-only Python library (RPA tool) for automating the PC WeChat client (version 3.9.12.xx) using the pywinauto framework. Its goal is to expose every built-in WeChat feature via simple Python APIs so users can script messages, files, calls, auto-replies, friends/groups settings, moments scraping, etc.

##### High-Level File Structure Analysis
- Top-level packaging:
– setup.py, setup.cfg, requirements.txt (dependencies: pywinauto, pillow, etc.)
– LICENSE, README.md, .gitignore
- Binaries & tools:
– inspect.exe (UI-inspector helper)
– wechat (wrapper or entry script)
- pics/: documentation images
- pywechat/: the main package
– Clock.py, Errors.py, Uielements.py, Warnings.py (core helpers & definitions)
– WechatTools.py (launch/attach to WeChat, open specific windows)
– WechatAuto.py (high-level automation classes: Messages, Files, Contacts, Moments, AutoReply, Call)
– WinSettings.py (Windows registry/env manipulations)
– utils.py (decorators and helper functions: auto_reply_to_group_decorator, listen_on_chat, dump_recent_moments, check_new_message, etc.)
- pyweixin/: a duplicate namespace (alias package for compatibility)
- test.ipynb: exploratory notebook
- utils.py: any small top-level helpers

##### README Insights
- Confirms the stack: Python 3.x + pywinauto + Windows 10/11
- Explains high-level modules and code examples
- Emphasizes single-threaded task scheduling, environment-variable detection, and auto-adding WeChat to PATH

##### Main Components
a. User Scripts / Consumer Code
b. pywechat Package
- WechatTools module
- WechatAuto module
- WinSettings module
- Uielements, Errors, Warnings
- utils module
c. External Library: pywinauto (plus its dependencies: pywin32, pillow, etc.)
d. Windows OS APIs: registry, environment variables, GUI subsystem
e. WeChat.exe Process (the target application)

##### Relationships & Data Flows
1. User script calls high-level APIs in pywechat.utils or pywechat.WechatAuto
2. These APIs coordinate via WechatTools to launch or attach to the WeChat.exe process
3. Uielements defines locators; Errors/Warnings define exception handling
4. pywechat invokes pywinauto APIs to drive the WeChat GUI: find windows, click buttons, read text
5. WinSettings may read/write registry or modify environment variables to register WeChat path
6. Results (messages, files, scraped data) return to user code as Python data structures

##### Architectural Patterns & Principles
- Layered design:
- Presentation/Entry (user scripts)
- API Facade (utils + WechatAuto)
- Core Services (WechatTools, WinSettings)
- UI Abstraction (Uielements + pywinauto)
- OS Integration (registry, environment)
- Single-threaded cooperative scheduling (Clock module)
- Exception encapsulation (Errors, Warnings)
- Namespacing to expose consistent import paths (pywechat vs. pyweixin)

##### Technologies & Frameworks
- Python 3.x
- pywinauto (UI automation)
- Windows GUI & Registry APIs
- Packaging tools: setuptools (setup.py), pip distribution
- (Optional) image libraries: pillow, OpenCV for any image-based automation

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        US["User Scripts / Consumer Code"]:::external
        CLI["CLI Wrapper (wechat)"]:::external
    end

    subgraph "API Facade Layer"
        UA["utils"]:::green
        WA["WechatAuto"]:::blue
    end

    subgraph "Core Services Layer"
        WT["WechatTools"]:::blue
        WS["WinSettings"]:::blue
    end

    subgraph "UI Abstraction Layer"
        UE["Uielements"]:::orange
        ER["Errors"]:::orange
        WR["Warnings"]:::orange
        CK["Clock"]:::green
    end

    subgraph "Alias Package"
        AP["pyweixin"]:::gray
    end

    subgraph "External Dependencies"
        PW["pywinauto"]:::gray
        OS["Windows OS APIs"]:::gray
        WC["WeChat.exe"]:::gray
        INS["inspect.exe"]:::gray
    end

    %% Data Flows
    US -->|"imports / calls"| UA
    US -->|"executes"| CLI
    CLI -->|"invokes APIs"| UA
    UA -->|"uses high-level automation"| WA
    WA -->|"coordinates core services"| WT
    UA -->|"applies decorators / scheduling"| CK
    CK -->|"schedules tasks for"| WA
    WT -->|"launch/attach"| PW
    PW -->|"drives GUI"| WC
    WT -->|"reads/writes"| OS
    WS -->|"manipulates registry/env"| OS
    UE -->|"defines locators for"| WT
    UE -->|"defines locators for"| WA
    ER -->|"encapsulate exceptions in"| UA
    ER -->|"encapsulate exceptions in"| WA
    WR -->|"warns on conditions in"| UA
    WR -->|"warns on conditions in"| WA
    AP -.->|"alias namespace for"| UA
    AP -.->|"alias namespace for"| WA
    AP -.->|"alias namespace for"| WT
    AP -.->|"alias namespace for"| WS

    %% Click Events
    click US "https://github.com/hello-mr-crab/pywechat/blob/main/test.ipynb"
    click CLI "https://github.com/hello-mr-crab/pywechat/tree/main/wechat"
    click UA "https://github.com/hello-mr-crab/pywechat/blob/main/pywechat/utils.py"
    click WA "https://github.com/hello-mr-crab/pywechat/blob/main/pywechat/WechatAuto.py"
    click WT "https://github.com/hello-mr-crab/pywechat/blob/main/pywechat/WechatTools.py"
    click WS "https://github.com/hello-mr-crab/pywechat/blob/main/pywechat/WinSettings.py"
    click UE "https://github.com/hello-mr-crab/pywechat/blob/main/pywechat/Uielements.py"
    click ER "https://github.com/hello-mr-crab/pywechat/blob/main/pywechat/Errors.py"
    click WR "https://github.com/hello-mr-crab/pywechat/blob/main/pywechat/Warnings.py"
    click CK "https://github.com/hello-mr-crab/pywechat/blob/main/pywechat/Clock.py"
    click AP "https://github.com/hello-mr-crab/pywechat/blob/main/pyweixin/__init__.py"
    click INS "https://github.com/hello-mr-crab/pywechat/blob/main/inspect.exe"

    %% Styles
    classDef blue fill:#cce5ff,stroke:#004085,color:#004085;
    classDef green fill:#d4edda,stroke:#155724,color:#155724;
    classDef orange fill:#fff3cd,stroke:#856404,color:#856404;
    classDef gray fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8f9fa,stroke:#343a40,color:#343a40;
    class US,CLI external
    class PW,OS,WC,INS gray
    class UA,CK green
    class WA,WT,WS blue
    class UE,ER,WR orange
```
