# javeleyqaq/wechatopendevtools-python architecture

> Architecture diagram of the GitHub repository javeleyqaq/wechatopendevtools-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/javeleyqaq/wechatopendevtools-python
- Repository: https://github.com/javeleyqaq/wechatopendevtools-python

## Overview

##### Project type and purpose
- This is a Python-based command-line tool (“WeChatOpenDevTools-Python”) whose purpose is to hook into the WeChat desktop application or its built-in browser and automatically enable F12 devtools (for WeChat mini-programs or the in-App browser). Its core functionality is process-injection and automation of WeChat’s developer tools UI.

##### File structure
- Top level:
- main.py: the CLI entry point, parses flags (`-x`, `-c`) and kicks off the hook flow.
- requirements.txt: Python dependencies.
- configs/: multiple JSON files keyed by WeChat mini-program version, used to locate memory addresses for patching.
- WechatOpenDevTools/: a Python package (wrapping process-attach & patch logic).
- utils/: helper modules (banner printing, colorized logs, common routines, WeChat-specific utilities).
- scripts/hook.js: the JavaScript shim that actually injects into the target process (via Node or an embedded JS engine).
- docs/: user documentation.
- workflows/: CI/CD definitions (GitHub Actions for dev and release).

##### README
- Describes supported WeChat versions, usage commands (`python main.py -x` to open mini-program F12, `-c` to open built-in browser F12), troubleshooting, and the fact that the code is a Python 3 rewrite of an existing Node.js tool.

##### Components
a. Main components
1. User/CLI Interface (main.py)
2. Configuration Manager (configs/*.json)
3. Hook Engine
– Python layer (WechatOpenDevTools package)
– JavaScript shim (scripts/hook.js)
4. Utilities (utils/*.py)
5. External WeChat Process (Windows or Mac desktop app)
6. CI/CD Pipeline (workflows/*.yml)
7. Documentation subsystem (docs/)—optional side component

b. Relationships and data flow
- User invokes `main.py` -> CLI parser
- CLI parser consults Configuration Manager to select JSON based on target WeChat version
- CLI calls into the Hook Engine (Python API in WechatOpenDevTools)
- Hook Engine loads and executes scripts/hook.js (via embedded JS runtime or Node child process)
- Hook Engine uses OS-level process APIs to attach to the WeChat process (using addresses from the config JSON)
- JS shim patches memory or injects code to enable F12 dev-tools
- Optionally, CI/CD workflows build and publish releases automatically

c. Architectural patterns and design principles
– Modular separation: CLI layer vs. business logic (WechatOpenDevTools) vs. low-level hook scripts
– Configuration-driven: JSON files isolate version-specific addresses from code
– Utility library: DRY principles in utils/ for logging, common routines, and process discovery
– CI/CD as code: workflows/ directory holds GitHub Actions definitions

d. Key technologies, frameworks, or libraries
– Python 3.9+
– JSON for configs
– Embedded JavaScript (Node.js or other JS engine) for hook.js
– GitHub Actions for dev.yml and release.yml
– pip requirements (psutil, pexpect, etc., as listed in requirements.txt)

- Entry points (CLI): rectangle in green
- Hook Engine (Python modules): rectangle in blue
- JS shim (scripts/hook.js): rectangle in purple
1. User → CLI
2. CLI → Config Manager (read JSON)
3. CLI → Hook Engine API
4. Hook Engine → JS shim (execute)
5. JS shim → WeChat Process (attach/inject)
6. WeChat Process → Hook Engine (callback or status)
7. Hook Engine → CLI (result)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    User["User"]:::external
    CLI["main.py"]:::cli
    User -->|"runs"| CLI

    %% Configuration Manager
    Config["configs/"]:::config
    CLI -->|"reads version JSON"| Config

    %% Hook Engine and Utilities
    subgraph "Hook Engine (Python)"
        direction TB
        EnginePy["WechatOpenDevTools/"]:::engine
        UtilsBanner["banner.py"]:::utils
        UtilsColors["colors.py"]:::utils
        UtilsCommons["commons.py"]:::utils
        UtilsWeChat["wechatutils.py"]:::utils
    end
    CLI -->|"calls API"| EnginePy
    EnginePy -->|"uses utils"| UtilsBanner
    EnginePy --> UtilsColors
    EnginePy --> UtilsCommons
    EnginePy --> UtilsWeChat

    %% JS Shim
    Shim["scripts/hook.js"]:::shim
    EnginePy -->|"executes shim"| Shim

    %% External WeChat Process
    External["WeChat Desktop App"]:::external
    Shim -->|"inject script"| External
    External -->|"status callback"| EnginePy
    EnginePy -->|"reports result"| CLI

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines" 
        direction TB
        DevWF["dev.yml"]:::ci
        ReleaseWF["release.yml"]:::ci
        WFReq["requirements.txt"]:::ci
    end
    push["push event"]:::external
    push --> DevWF
    push --> ReleaseWF
    WFReq --> DevWF
    WFReq --> ReleaseWF

    %% Documentation
    Docs["docs/"]:::docs

    %% Click Events
    click CLI "https://github.com/javeleyqaq/wechatopendevtools-python/blob/main/main.py"
    click Config "https://github.com/javeleyqaq/wechatopendevtools-python/tree/main/configs/"
    click EnginePy "https://github.com/javeleyqaq/wechatopendevtools-python/tree/main/WechatOpenDevTools/"
    click Shim "https://github.com/javeleyqaq/wechatopendevtools-python/blob/main/scripts/hook.js"
    click UtilsBanner "https://github.com/javeleyqaq/wechatopendevtools-python/blob/main/utils/banner.py"
    click UtilsColors "https://github.com/javeleyqaq/wechatopendevtools-python/blob/main/utils/colors.py"
    click UtilsCommons "https://github.com/javeleyqaq/wechatopendevtools-python/blob/main/utils/commons.py"
    click UtilsWeChat "https://github.com/javeleyqaq/wechatopendevtools-python/blob/main/utils/wechatutils.py"
    click DevWF "https://github.com/javeleyqaq/wechatopendevtools-python/blob/main/workflows/dev.yml"
    click ReleaseWF "https://github.com/javeleyqaq/wechatopendevtools-python/blob/main/workflows/release.yml"
    click WFReq "https://github.com/javeleyqaq/wechatopendevtools-python/blob/main/workflows/requirements.txt"
    click Docs "https://github.com/javeleyqaq/wechatopendevtools-python/tree/main/docs/"

    %% Styles
    classDef cli fill:#a8f0a0,stroke:#333
    classDef config fill:#f0c080,stroke:#333
    classDef engine fill:#80c0f0,stroke:#333
    classDef shim fill:#d0a0f0,stroke:#333
    classDef utils fill:#e0e0e0,stroke:#333
    classDef external fill:#dddddd,stroke:#333
    classDef ci fill:#f8f8f8,stroke:#333,stroke-dasharray:5 5
    classDef docs fill:#f0f0f0,stroke:#333
```
