# ihongren/hpack architecture

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

- Interactive diagram: https://gitdiagram.com/ihongren/hpack
- Repository: https://github.com/ihongren/hpack

## Overview

##### Project Type and Purpose
- **Type**: Open-source command-line tool (Python)
- **Purpose**: Automates building (via hvigorw), packaging, signing (Java jars), manifest generation, HTML index page creation (templating), QR code generation, and optional upload (OSS or custom) for HarmonyOS internal testing.

##### File Structure
- **src/harmony_hpack/**: core Python modules
- `main.py` – CLI entry point and command dispatcher
- `PackFile.py` – post-pack callback hooks (extensibility)
- `config.py` – static `Config` class (server, signing, template settings)
- `packSign.py`, `signInfo.py`, `template.py`, `toolConfig.py` – core logic modules
- `hdc.py` – device listing via `hdc`
- `hdc` & `hvigorw` tool adapters
- `hap-manifest-sign-tool` folder (Java JARs, libs)
- `templates/` – built-in HTML templates
- **setup.py** – packaging for PyPI
- **demo/** – example HarmonyOS project, showing how hpack is used
- **oh_modules/** – package dependencies for demo

##### README for Additional Insights
- **Commands**: `hpack init`, `hpack pack`, `hpack install`, `hpack targets`, `hpack template`, `hpack -u`
- **Workflow**:
a. Read `config.py`
b. Invoke hvigorw to assemble HAP/HSP
c. Sign packages via Java tool (`manifest-sign-tool.jar`)
d. Generate signed `manifest.json5`
e. Generate index HTML (choose & render template)
f. Generate QR code
g. Optional: upload artifacts via OSS SDK or custom `PackFile.py` hook
h. Provide CLI feedback

##### Main Components and Their Relationships
a. **CLI Frontend** (main.py)
- Parses user commands & flags
- Routes to individual handlers (init, pack, install, etc.)
b. **Config Module** (config.py)
- Holds server URLs, keys, passwords, template choice, debug flags
- Read-only at runtime
c. **Build Adapter** (toolConfig.py + hvigorw binary)
- Constructs and executes hvigorw commands
- Produces `.hap` and `.hsp` artifacts
d. **Signing Engine**
- Python wrapper (`packSign.py`, `signInfo.py`)
- Java-based `manifest-sign-tool.jar` + BouncyCastle libs
- Consumes raw artifacts + .cer/.p7b/.p12 to produce signed artifacts & manifest
e. **Template Renderer** (template.py + templates/)
- Loads HTML template based on `Config.IndexTemplate`
- Substitutes variables (version, size, URLs, QR code image)
- Emits `index.html` in `hpack/build/{product}`
f. **QR Code Generator** (utility within template or signInfo)
- Renders QR images pointing to manifest or install URL
g. **Uploader / Callback Hook** (PackFile.py)
- Default: no-op or prints results
- Customizable: user can implement `didPack(packInfo)` to push to OSS or another server
- Uses `oss2` library if OSS is chosen
h. **Device Inspector** (hdc.py)
- Uses Huawei Device Connector (`hdc`) to list targets, retrieve UDID
- Implements `hpack targets` and `hpack -u`

##### Architectural Patterns & Design Principles
- **Modular CLI**: One command per handler, clear separation
- **Adapter Pattern**: Tool adapters for hvigorw & hdc to isolate external dependencies
- **Strategy / Plugin Hook**: `PackFile.py` as user-extensible callback for uploading
- **Template Strategy**: Multiple HTML templates loaded at runtime
- **Configuration-Driven**: `Config` centralizes all environment-specific settings

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI and Config
    subgraph "CLI Layer"
        CLI["CLI Frontend"]:::python
    end
    Config["Config Module"]:::python
    CLI -->|"reads config"| Config

    %% Build Adapter
    subgraph "Build Adapter"
        TA["ToolConfig (Build Adapter)"]:::python
        HV["hvigorw Binary"]:::ext
    end
    CLI -->|"executes build"| TA
    TA -->|"executes assembleHap"| HV
    HV -->|"produces .hap/.hsp"| OutputBuild[(Build Output)]:::fs

    %% Signing Engine
    subgraph "Signing Engine"
        PS["packSign.py"]:::python
        SI["signInfo.py"]:::python
        JT["Java Signing Tool\n(hap-manifest-sign-tool/)"]:::ext
    end
    CLI -->|"invokes signing"| PS
    PS -->|"uses sign info"| SI
    SI -->|"calls jar"| JT
    JT -->|"produces signed artifacts\n& manifest.json5"| OutputSigned[(Signed Artifacts)]:::fs

    %% Template Renderer & QR
    subgraph "Template Renderer"
        TR["template.py"]:::python
        TPL["templates/"]:::fs
    end
    QR["QR Code Generator"]:::python
    PS -->|"passes manifest"| TR
    TR -->|"loads template"| TPL
    TR -->|"renders index.html"| OutputIndex[(Output Folder)]:::fs
    TR -->|"invokes qr utility"| QR
    QR -->|"embeds QR image"| OutputIndex

    %% Uploader Hook
    subgraph "Uploader / Callback Hook"
        PF["PackFile.py"]:::python
        OSS["OSS Service"]:::cloud
    end
    CLI -->|"calls didPack()"| PF
    PF -->|"uploads via oss2"| OSS
    PF -->|optional custom| ExternalServer["Custom Server"]:::cloud

    %% Device Inspector
    subgraph "Device Inspector"
        HDC["hdc.py"]:::python
        HDCbin["hdc Binary"]:::ext
    end
    CLI -->|"queries devices"| HDC
    HDC -->|"executes hdc"| HDCbin
    HDCbin -->|"returns UDIDs"| CLI

    %% File system components
    ConfigFS["config.py"]:::fs
    TPLFS["templates/"]:::fs
    BuildFS["hpack/build/"]:::fs

    %% Click events
    click CLI "https://github.com/ihongren/hpack/blob/main/src/harmony_hpack/main.py"
    click Config "https://github.com/ihongren/hpack/blob/main/src/harmony_hpack/config.py"
    click TA "https://github.com/ihongren/hpack/blob/main/src/harmony_hpack/toolConfig.py"
    click PS "https://github.com/ihongren/hpack/blob/main/src/harmony_hpack/packSign.py"
    click SI "https://github.com/ihongren/hpack/blob/main/src/harmony_hpack/signInfo.py"
    click JT "https://github.com/ihongren/hpack/tree/main/src/harmony_hpack/hap-manifest-sign-tool/"
    click TR "https://github.com/ihongren/hpack/blob/main/src/harmony_hpack/template.py"
    click TPL "https://github.com/ihongren/hpack/tree/main/src/harmony_hpack/templates/"
    click QR "https://github.com/ihongren/hpack/blob/main/src/harmony_hpack/utils.py"
    click PF "https://github.com/ihongren/hpack/blob/main/src/harmony_hpack/PackFile.py"
    click HDC "https://github.com/ihongren/hpack/blob/main/src/harmony_hpack/hdc.py"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef ext fill:#FFA500,stroke:#333,stroke-width:1px
    classDef fs fill:#90EE90,stroke:#333,stroke-width:1px
    classDef cloud fill:#DDA0DD,stroke:#333,stroke-width:1px
```
