# 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 `TextAsset`s.
  `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.