Hi3-Patcher/docs/architecture.md

Architecture

format/ holds reusable binary-format parsing; patch/ holds the patch logic. Patch modules depend on format/, android/ and util/, never on each other.

format/

All reads are bounds-checked; malformed input returns an error instead of panicking.

• bytes — little/big-endian integer reads and writes, slicing, power-of-two alignment.
• pe — PE32+ (x86-64) reader. Validates headers and section ranges; provides section lookup, RVA→offset mapping, data directories, export lookup, and a stricter image-bound check used by ACE and HoYoKProtect. Patches add their own layout checks on top.
• elf — ARM64 shared-object reader. Validates headers and section/segment ranges; provides sections, segments, .dynsym symbols, RELA entries, and address→file-offset mapping through PT_LOAD.
• dex — field access, checksum recompute (SHA-1 + Adler-32), string and const-string lookup, and append_string, which inserts a string_data_item before the annotations section and relocates every later offset, map entry and header field.
• unity — UnityFS v6 bundles and serialized-file TextAssets. rebuild re-encodes only changed blocks and re-verifies the result. replace_script and Bundle::replace_node resize a TextAsset or bundle node, rewriting object offsets, the header size and the node directory. Blocks may be uncompressed or LZ4.

patch/

region maps the Windows client's ChannelConfig (ChannelName/BundleIdentifier) to one of six PC regions (CN/GLB/JP/KR/TW/SEA) with its SDK key and environment id.

Single-file Windows writes (RSA, ACE, HoYoKProtect) use util::replace::verified: write a sibling temporary file, flush, read it back, re-check the target for concurrent changes, persist, re-verify. The dispatch patch replaces its three files together and rolls back on failure.

android/

toolchain finds Build-Tools and Java 17+, or downloads them (SHA-256 verified). sign::signed_patch runs a patch's repack, which drops the old signature entries, into a temporary APK, then zip-aligns it (-P 16 -f 4), signs and verifies it with apksigner, and writes <name>_patched.apk.

cli/

interactive is the terminal menu (no arguments). args parses <command> --flag value (or --flag=value) and validates the whole command line before running the patch, then reports via exit code and optional JSON.