# mercuryworkshop/sh1mmer architecture

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

- Interactive diagram: https://gitdiagram.com/mercuryworkshop/sh1mmer
- Repository: https://github.com/mercuryworkshop/sh1mmer

## Overview

SH1MMER is a ChromeOS RMA-shim modification toolkit, with a companion browser-based builder. The principal workflow is to supply a raw RMA shim, build a modified image, flash and boot it on a Chromebook, then use the resulting shim interface. The repository also includes firmware/GPT image utilities and separate legacy and beautiful-world shim runtimes. README documents the build and boot sequence; the source excerpts show Python utility relationships and the browser builder’s emulator setup. Other runtime wiring is not shown, so uncertain links are omitted.

Main entry points: [`wax4web/wax4web.js`](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax4web/wax4web.js) (Wax4Web interface), [`wax/lib/py/image_tool.py`](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/lib/py/image_tool.py) (Image manipulation), [`wax/wax.sh`](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/wax.sh) (Wax build entry), [`wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_main.sh`](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_main.sh) (Shim main interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Image building"]
  node_wax["Wax build entry<br/>[wax.sh]"]
  node_archives["Kernel checks and archives<br/>[kernarchive.sh]"]
end

subgraph group_utilities["Image utilities"]
  node_image["Image manipulation<br/>[image_tool.py]"]
  node_gpt["GPT operations<br/>[pygpt.py]"]
  node_fmap["FMAP codec<br/>[fmap.py]"]
  node_netboot["Firmware settings"]
end

subgraph group_runtime["Shim runtime"]
  node_bootstrap["Shim bootstrap<br/>[init_sh1mmer.sh]"]
  node_init["Shim init"]
  node_main["Shim main interface<br/>[sh1mmer_main.sh]"]
  node_gui["Beautiful World GUI<br/>[sh1mmer_gui.sh]"]
  node_options["Options and payloads"]
  node_payload["Payload launcher<br/>[sh1mmer_payload.sh]"]
  node_payloads["Payload collection"]
end

subgraph group_web["Browser builder"]
  node_webui["Wax4Web interface<br/>[wax4web.js]"]
  node_v86["v86 emulator<br/>[libv86.js]"]
  node_webassets["Emulator assets"]
end

node_operator(("Builder / user"))
node_rma["Raw RMA shim"]
node_flasher["USB flasher"]
node_chromebook["Chromebook"]
node_download["Built image download"]

node_operator -->|"provides"| node_rma
node_operator -->|"runs build"| node_wax
node_rma -->|"input image"| node_wax
node_wax -.->|"builds image"| node_image
node_image -->|"uses GPT utility"| node_gpt
node_image -->|"uses FMAP codec"| node_fmap
node_image -->|"imports settings"| node_netboot
node_wax -.->|"checks kernel"| node_archives
node_operator -->|"flashes image"| node_flasher
node_flasher -->|"writes image"| node_chromebook
node_chromebook -->|"boots shim"| node_bootstrap
node_bootstrap -.->|"starts runtime"| node_init
node_init -.->|"starts interface"| node_main
node_main -.->|"offers GUI"| node_gui
node_main -.->|"offers options"| node_options
node_options -.->|"launches payloads"| node_payload
node_payload -.->|"runs scripts"| node_payloads
node_operator -.->|"opens builder"| node_webui
node_webui -->|"starts emulator"| node_v86
node_webui -->|"loads assets"| node_webassets
node_webui -->|"uploads shim"| node_rma
node_webui -->|"offers image"| node_download

click node_wax "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/wax.sh"
click node_image "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/lib/py/image_tool.py"
click node_gpt "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/lib/py/pygpt.py"
click node_fmap "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/lib/py/fmap.py"
click node_netboot "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/lib/py/netboot_firmware_settings.py"
click node_archives "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/kernarchive.sh"
click node_bootstrap "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/bootstrap/noarch/init_sh1mmer.sh"
click node_init "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/init"
click node_main "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_main.sh"
click node_gui "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_gui.sh"
click node_options "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_optionsSelector.sh"
click node_payload "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_payload.sh"
click node_payloads "https://github.com/mercuryworkshop/sh1mmer/tree/beautifulworld/wax/payloads"
click node_webui "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax4web/wax4web.js"
click node_v86 "https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax4web/libv86.js"
click node_webassets "https://github.com/mercuryworkshop/sh1mmer/tree/beautifulworld/wax4web"

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_wax,node_archives,node_operator toneBlue
class node_image,node_gpt,node_fmap,node_netboot toneAmber
class node_bootstrap,node_init,node_main,node_gui,node_options,node_payload,node_payloads toneMint
class node_webui,node_v86,node_webassets toneRose
class node_rma,node_flasher,node_chromebook,node_download toneIndigo
```

## Components

### Image building

- [Wax build entry](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/wax.sh): `wax/wax.sh`
- [Kernel checks and archives](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/kernarchive.sh): `wax/kernarchive.sh`

### Image utilities

- [Image manipulation](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/lib/py/image_tool.py): `wax/lib/py/image_tool.py`
- [GPT operations](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/lib/py/pygpt.py): `wax/lib/py/pygpt.py`
- [FMAP codec](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/lib/py/fmap.py): `wax/lib/py/fmap.py`
- [Firmware settings](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/lib/py/netboot_firmware_settings.py): `wax/lib/py/netboot_firmware_settings.py`

### Shim runtime

- [Shim bootstrap](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/bootstrap/noarch/init_sh1mmer.sh): `wax/sh1mmer_bw/bootstrap/noarch/init_sh1mmer.sh`
- [Shim init](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/init): `wax/sh1mmer_bw/init`
- [Shim main interface](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_main.sh): `wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_main.sh`
- [Beautiful World GUI](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_gui.sh): `wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_gui.sh`
- [Options and payloads](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_optionsSelector.sh): `wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_optionsSelector.sh`
- [Payload launcher](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_payload.sh): `wax/sh1mmer_bw/root/noarch/usr/sbin/sh1mmer_payload.sh`
- [Payload collection](https://github.com/mercuryworkshop/sh1mmer/tree/beautifulworld/wax/payloads): `wax/payloads`

### Browser builder

- [Wax4Web interface](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax4web/wax4web.js): `wax4web/wax4web.js`
- [v86 emulator](https://github.com/mercuryworkshop/sh1mmer/blob/beautifulworld/wax4web/libv86.js): `wax4web/libv86.js`
- [Emulator assets](https://github.com/mercuryworkshop/sh1mmer/tree/beautifulworld/wax4web): `wax4web`

### Other components

- **Builder / user**
- **Raw RMA shim**
- **USB flasher**
- **Chromebook**
- **Built image download**

## Connections

- Builder / user → Raw RMA shim: provides (evidence: `README.md`)
- Builder / user → Wax build entry: runs build (evidence: `README.md`)
- Raw RMA shim → Wax build entry: input image (evidence: `README.md`)
- Wax build entry → Image manipulation: builds image
- Image manipulation → GPT operations: uses GPT utility (evidence: `wax/lib/py/image_tool.py`)
- Image manipulation → FMAP codec: uses FMAP codec (evidence: `wax/lib/py/image_tool.py`)
- Image manipulation → Firmware settings: imports settings (evidence: `wax/lib/py/image_tool.py`)
- Wax build entry → Kernel checks and archives: checks kernel
- Builder / user → USB flasher: flashes image (evidence: `README.md`)
- USB flasher → Chromebook: writes image (evidence: `README.md`)
- Chromebook → Shim bootstrap: boots shim (evidence: `README.md`)
- Shim bootstrap → Shim init: starts runtime
- Shim init → Shim main interface: starts interface
- Shim main interface → Beautiful World GUI: offers GUI
- Shim main interface → Options and payloads: offers options
- Options and payloads → Payload launcher: launches payloads
- Payload launcher → Payload collection: runs scripts
- Builder / user → Wax4Web interface: opens builder
- Wax4Web interface → v86 emulator: starts emulator (evidence: `wax4web/wax4web.js`)
- Wax4Web interface → Emulator assets: loads assets (evidence: `wax4web/wax4web.js`)
- Wax4Web interface → Raw RMA shim: uploads shim (evidence: `wax4web/wax4web.js`)
- Wax4Web interface → Built image download: offers image (evidence: `wax4web/wax4web.js`)
