# lythka/hao-patcher architecture

> Architecture diagram of the GitHub repository lythka/hao-patcher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lythka/hao-patcher
- Repository: https://github.com/lythka/hao-patcher

## Overview

hao-patcher builds a layered macOS 27 image for unsupported Intel Macs, then guides the user through making a USB installer and installing it. The main path runs from hardware/profile selection through image assembly and compatibility patches to image deployment; distinct branches provide accelerated Metal support and image capture/push tools. The README documents the image layers and capabilities, while sampled source confirms builder dependencies and selected tool internals; unsampled subsystem links are omitted where their callers are not shown.

Main entry points: [`tools/hao/src/builder.py`](https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/builder.py) (Build orchestration), [`pipeline/stages/golden-image.py`](https://github.com/lythka/hao-patcher/blob/main/pipeline/stages/golden-image.py) (Golden image), [`tools/ssdimg/cli.py`](https://github.com/lythka/hao-patcher/blob/main/tools/ssdimg/cli.py) (SSD image workflow), [`tools/hao/src/installer.py`](https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/installer.py) (USB installer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_install["Installer workflow"]
  node_installer["USB installer<br/>[installer.py]"]
  node_builder["Build orchestration<br/>[builder.py]"]
  node_detection["Hardware detection<br/>[detect.py]"]
  node_safety["Install safety<br/>[safety.py]"]
  node_stick["USB writing<br/>[stick.py]"]
end

subgraph group_assembly["Image assembly"]
  node_assembly_plan["Assembly recipes<br/>[patches.py]"]
  node_golden_image["Golden image<br/>[golden-image.py]"]
end

subgraph group_compat["Compatibility fixes"]
  node_edit_engine["Binary edit engine<br/>[engine.py]"]
  node_edit_specs["Edit specifications<br/>[spec.py]"]
  node_cache_dylib["Cache dylib extraction<br/>[cache_dylib.py]"]
  node_user_patches["System compatibility"]
  node_kernel_patches["Kernel compatibility"]
end

subgraph group_graphics["Metal graphics"]
  node_metallib["Shader library fixes"]
  node_metal_argbuf["Argument buffers"]
  node_gpu_client["GPU sampler client<br/>[gpu_client.c]"]
  node_sampler_query["Sampler query interpose<br/>[sampler_query.c]"]
end

subgraph group_imaging["Image tools"]
  node_disk_image["SSD image workflow<br/>[cli.py]"]
  node_image_store[("Image object store<br/>[store.py]")]
  node_image_push["Disk image transfer<br/>[push.py]"]
  node_push_agent["Target disk agent<br/>[agent.c]"]
  node_swift_graph["Swift cache graph<br/>[swift_graph.py]"]
  node_swift_metadata["Swift metadata<br/>[swift_metadata.py]"]
end

node_user(("Mac owner"))

node_user -->|"creates USB"| node_installer
node_installer -->|"uses plan"| node_builder
node_builder -->|"resolves profile"| node_detection
node_builder -->|"checks safety"| node_safety
node_builder -->|"delegates USB"| node_stick
node_builder -->|"plans recipes"| node_assembly_plan
node_builder -.->|"assembles image"| node_golden_image
node_assembly_plan -.->|"selects fixes"| node_user_patches
node_golden_image -->|"includes kernel layer"| node_kernel_patches
node_golden_image -->|"includes compatibility layer"| node_user_patches
node_golden_image -->|"includes shader repairs"| node_metallib
node_metallib -->|"pairs with compiler support"| node_metal_argbuf
node_gpu_client -->|"avoids loading"| node_sampler_query
node_edit_engine -->|"applies spec"| node_edit_specs
node_disk_image -->|"stores chunks"| node_image_store
node_disk_image -->|"pushes image"| node_image_push
node_image_push -->|"streams chunks"| node_push_agent
node_swift_graph -->|"coverage reads"| node_swift_metadata

click node_installer "https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/installer.py"
click node_builder "https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/builder.py"
click node_detection "https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/detect.py"
click node_safety "https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/safety.py"
click node_stick "https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/stick.py"
click node_assembly_plan "https://github.com/lythka/hao-patcher/blob/main/pipeline/patches.py"
click node_golden_image "https://github.com/lythka/hao-patcher/blob/main/pipeline/stages/golden-image.py"
click node_disk_image "https://github.com/lythka/hao-patcher/blob/main/tools/ssdimg/cli.py"
click node_image_store "https://github.com/lythka/hao-patcher/blob/main/tools/ssdimg/store.py"
click node_image_push "https://github.com/lythka/hao-patcher/blob/main/tools/ssdimg/push.py"
click node_push_agent "https://github.com/lythka/hao-patcher/blob/main/tools/ssdpush/agent.c"
click node_edit_engine "https://github.com/lythka/hao-patcher/blob/main/tools/edit-engine/src/engine.py"
click node_edit_specs "https://github.com/lythka/hao-patcher/blob/main/tools/edit-engine/src/spec.py"
click node_cache_dylib "https://github.com/lythka/hao-patcher/blob/main/tools/cache-dylib/cache_dylib.py"
click node_user_patches "https://github.com/lythka/hao-patcher/tree/main/patches/golden-gate-userspace/src"
click node_kernel_patches "https://github.com/lythka/hao-patcher/tree/main/patches/darwin27-kernel/src"
click node_metallib "https://github.com/lythka/hao-patcher/tree/main/cache/metallib/lib"
click node_metal_argbuf "https://github.com/lythka/hao-patcher/tree/main/tools/metal-argbuf/src/compiler"
click node_gpu_client "https://github.com/lythka/hao-patcher/blob/main/cache/metallib/lib/runtime/gpu_client.c"
click node_sampler_query "https://github.com/lythka/hao-patcher/blob/main/cache/metallib/lib/runtime/sampler_query.c"
click node_swift_graph "https://github.com/lythka/hao-patcher/blob/main/tools/shared-cache/src/dyld_rebuild/swift_graph.py"
click node_swift_metadata "https://github.com/lythka/hao-patcher/blob/main/tools/shared-cache/src/dyld_rebuild/swift_metadata.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_installer,node_builder,node_detection,node_safety,node_stick toneBlue
class node_assembly_plan,node_golden_image toneAmber
class node_edit_engine,node_edit_specs,node_cache_dylib,node_user_patches,node_kernel_patches toneMint
class node_metallib,node_metal_argbuf,node_gpu_client,node_sampler_query toneRose
class node_disk_image,node_image_store,node_image_push,node_push_agent,node_swift_graph,node_swift_metadata,node_user toneIndigo
```

## Components

### Installer workflow

- [USB installer](https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/installer.py): `tools/hao/src/installer.py`
- [Build orchestration](https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/builder.py): `tools/hao/src/builder.py`
- [Hardware detection](https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/detect.py): `tools/hao/src/detect.py`
- [Install safety](https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/safety.py): `tools/hao/src/safety.py`
- [USB writing](https://github.com/lythka/hao-patcher/blob/main/tools/hao/src/stick.py): `tools/hao/src/stick.py`

### Image assembly

- [Assembly recipes](https://github.com/lythka/hao-patcher/blob/main/pipeline/patches.py): `pipeline/patches.py`
- [Golden image](https://github.com/lythka/hao-patcher/blob/main/pipeline/stages/golden-image.py): `pipeline/stages/golden-image.py`

### Compatibility fixes

- [Binary edit engine](https://github.com/lythka/hao-patcher/blob/main/tools/edit-engine/src/engine.py): `tools/edit-engine/src/engine.py`
- [Edit specifications](https://github.com/lythka/hao-patcher/blob/main/tools/edit-engine/src/spec.py): `tools/edit-engine/src/spec.py`
- [Cache dylib extraction](https://github.com/lythka/hao-patcher/blob/main/tools/cache-dylib/cache_dylib.py): `tools/cache-dylib/cache_dylib.py`
- [System compatibility](https://github.com/lythka/hao-patcher/tree/main/patches/golden-gate-userspace/src): `patches/golden-gate-userspace/src`
- [Kernel compatibility](https://github.com/lythka/hao-patcher/tree/main/patches/darwin27-kernel/src): `patches/darwin27-kernel/src`

### Metal graphics

- [Shader library fixes](https://github.com/lythka/hao-patcher/tree/main/cache/metallib/lib): `cache/metallib/lib`
- [Argument buffers](https://github.com/lythka/hao-patcher/tree/main/tools/metal-argbuf/src/compiler): `tools/metal-argbuf/src/compiler`
- [GPU sampler client](https://github.com/lythka/hao-patcher/blob/main/cache/metallib/lib/runtime/gpu_client.c): `cache/metallib/lib/runtime/gpu_client.c`
- [Sampler query interpose](https://github.com/lythka/hao-patcher/blob/main/cache/metallib/lib/runtime/sampler_query.c): `cache/metallib/lib/runtime/sampler_query.c`

### Image tools

- [SSD image workflow](https://github.com/lythka/hao-patcher/blob/main/tools/ssdimg/cli.py): `tools/ssdimg/cli.py`
- [Image object store](https://github.com/lythka/hao-patcher/blob/main/tools/ssdimg/store.py): `tools/ssdimg/store.py`
- [Disk image transfer](https://github.com/lythka/hao-patcher/blob/main/tools/ssdimg/push.py): `tools/ssdimg/push.py`
- [Target disk agent](https://github.com/lythka/hao-patcher/blob/main/tools/ssdpush/agent.c): `tools/ssdpush/agent.c`
- [Swift cache graph](https://github.com/lythka/hao-patcher/blob/main/tools/shared-cache/src/dyld_rebuild/swift_graph.py): `tools/shared-cache/src/dyld_rebuild/swift_graph.py`
- [Swift metadata](https://github.com/lythka/hao-patcher/blob/main/tools/shared-cache/src/dyld_rebuild/swift_metadata.py): `tools/shared-cache/src/dyld_rebuild/swift_metadata.py`

### Other components

- **Mac owner**

## Connections

- Mac owner → USB installer: creates USB (evidence: `README.md`)
- USB installer → Build orchestration: uses plan (evidence: `tools/hao/src/installer.py`)
- Build orchestration → Hardware detection: resolves profile (evidence: `tools/hao/src/builder.py`)
- Build orchestration → Install safety: checks safety (evidence: `tools/hao/src/builder.py`)
- Build orchestration → USB writing: delegates USB (evidence: `tools/hao/src/builder.py`)
- Build orchestration → Assembly recipes: plans recipes (evidence: `tools/hao/src/builder.py`)
- Build orchestration → Golden image: assembles image
- Assembly recipes → System compatibility: selects fixes
- Golden image → Kernel compatibility: includes kernel layer (evidence: `README.md`)
- Golden image → System compatibility: includes compatibility layer (evidence: `README.md`)
- Golden image → Shader library fixes: includes shader repairs (evidence: `README.md`)
- Shader library fixes → Argument buffers: pairs with compiler support (evidence: `README.md`)
- GPU sampler client → Sampler query interpose: avoids loading (evidence: `cache/metallib/lib/runtime/gpu_client.c`)
- Binary edit engine → Edit specifications: applies spec (evidence: `tools/edit-engine/src/engine.py`)
- SSD image workflow → Image object store: stores chunks (evidence: `tools/ssdimg/cli.py`)
- SSD image workflow → Disk image transfer: pushes image (evidence: `tools/ssdimg/cli.py`)
- Disk image transfer → Target disk agent: streams chunks (evidence: `tools/ssdpush/agent.c`)
- Swift cache graph → Swift metadata: coverage reads (evidence: `tools/shared-cache/src/dyld_rebuild/swift_coverage.py`)
