# riftaway7-code/anathema architecture

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

- Interactive diagram: https://gitdiagram.com/riftaway7-code/anathema
- Repository: https://github.com/riftaway7-code/anathema

## Overview

Anathema is a research project for booting an arm64 macOS virtual-machine kernel on x86-64. Its principal path is preparing macOS media, installing the loader to USB, gathering hardware readiness information, then loading the kernel and device tree and executing them in the virtual arm64 runtime. The runtime combines translation, memory management, and virtual devices. The graph also preserves the documented media-tooling and installer capabilities. Some subsystem wiring is documented only at README level; dashed edges mark relationships not verified in excerpts.

Main entry points: [`crates/anathema-media/src/main.rs`](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/main.rs) (IPSW tools), [`crates/anathema-rt/src/machine.rs`](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/machine.rs) (ARM machine), [`crates/anathema-boot/src/main.rs`](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/main.rs) (UEFI menu), [`crates/anathema-rt/src/mem.rs`](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/mem.rs) (RAM and bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_media["Media tooling"]
  node_media_cli["IPSW tools<br/>[main.rs]"]
  node_feed_download["Feed and download<br/>[download.rs]"]
  node_archive["ZIP and plist<br/>[zip.rs]"]
  node_im4p["IM4P unwrap<br/>[im4p.rs]"]
  node_aea["AEA decrypt<br/>[aea.rs]"]
  node_apfs["APFS reader<br/>[apfs.rs]"]
  node_dsc["dyld cache reader<br/>[dsc.rs]"]
end

subgraph group_setup["USB installer"]
  node_setup_ui["Installer UI<br/>[main.rs]"]
  node_installer["Disk installer<br/>[install.rs]"]
  node_disk["Disk operations<br/>[disk.rs]"]
end

subgraph group_boot["UEFI loader"]
  node_boot_menu["UEFI menu<br/>[main.rs]"]
  node_inventory["Hardware inventory<br/>[report.rs]"]
  node_readiness["Readiness check<br/>[readiness.rs]"]
  node_bringup["Hardware bring-up<br/>[mod.rs]"]
  node_apic["APIC and SMP<br/>[apic.rs]"]
  node_nvme["NVMe and GPT<br/>[nvme.rs]"]
  node_macboot["macOS loader<br/>[macboot.rs]"]
  node_exfat["exFAT reader<br/>[exfat.rs]"]
end

subgraph group_runtime["Virtual machine"]
  node_runtime_entry["Runtime harness<br/>[main.rs]"]
  node_machine["ARM machine<br/>[machine.rs]"]
  node_memory["RAM and bus<br/>[mem.rs]"]
  node_mmu["Software MMU<br/>[mmu.rs]"]
  node_gic["GICv3<br/>[gic.rs]"]
  node_rt_pci["PCIe virtio<br/>[pci.rs]"]
  node_aesdev["AES device<br/>[aesdev.rs]"]
  node_simd["SIMD fallbacks<br/>[simd.rs]"]
  node_macho["Mach-O loader<br/>[macho.rs]"]
end

subgraph group_translator["Instruction translation"]
  node_decode["AArch64 decoder<br/>[decode.rs]"]
  node_translate["x86 emitter<br/>[trans.rs]"]
  node_run["Block runner<br/>[run.rs]"]
end

node_user(("Operator"))
node_ipsw["macOS IPSW"]
node_usb[("USB stick")]
node_host(("x86-64 host"))

node_user -.->|"prepares media"| node_media_cli
node_ipsw -.->|"provides image"| node_media_cli
node_media_cli -.->|"uses"| node_feed_download
node_media_cli -.->|"unpacks"| node_archive
node_media_cli -.->|"unwraps"| node_im4p
node_media_cli -.->|"decrypts"| node_aea
node_media_cli -.->|"reads"| node_apfs
node_media_cli -.->|"reads"| node_dsc
node_user -->|"starts installation"| node_setup_ui
node_setup_ui -->|"starts install"| node_installer
node_installer -->|"writes drive"| node_disk
node_installer -->|"prepares"| node_usb
node_usb -.->|"boots"| node_boot_menu
node_host -.->|"starts UEFI app"| node_boot_menu
node_boot_menu -->|"collects report"| node_inventory
node_inventory -->|"supplies inventory"| node_readiness
node_boot_menu -->|"runs test"| node_bringup
node_bringup -->|"uses"| node_apic
node_bringup -->|"uses"| node_nvme
node_boot_menu -->|"dispatches boot"| node_macboot
node_macboot -.->|"reads RAM disk"| node_exfat
node_macboot -.->|"runs runtime"| node_runtime_entry
node_runtime_entry -->|"loads kernel image"| node_macho
node_runtime_entry -->|"executes guest"| node_machine
node_machine -->|"accesses memory bus"| node_memory
node_machine -->|"translates addresses"| node_mmu
node_machine -->|"dispatches device I/O"| node_aesdev
node_machine -->|"dispatches PCI I/O"| node_rt_pci
node_memory -->|"routes register access"| node_gic
node_memory -->|"backs device DMA"| node_aesdev
node_memory -->|"backs device access"| node_rt_pci
node_machine -.->|"uses fallbacks"| node_simd
node_machine -.->|"runs translated blocks"| node_run
node_run -.->|"requests translation"| node_translate
node_translate -->|"decodes instructions"| node_decode

click node_media_cli "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/main.rs"
click node_feed_download "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/download.rs"
click node_archive "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/zip.rs"
click node_im4p "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/im4p.rs"
click node_aea "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/aea.rs"
click node_apfs "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/apfs.rs"
click node_dsc "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/dsc.rs"
click node_setup_ui "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-setup/src/main.rs"
click node_installer "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-setup/src/install.rs"
click node_disk "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-setup/src/disk.rs"
click node_boot_menu "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/main.rs"
click node_inventory "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/report.rs"
click node_readiness "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/readiness.rs"
click node_bringup "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/bringup/mod.rs"
click node_apic "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/bringup/apic.rs"
click node_nvme "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/bringup/nvme.rs"
click node_macboot "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/macboot.rs"
click node_exfat "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/exfat.rs"
click node_runtime_entry "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/main.rs"
click node_machine "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/machine.rs"
click node_memory "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/mem.rs"
click node_mmu "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/mmu.rs"
click node_gic "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/gic.rs"
click node_rt_pci "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/pci.rs"
click node_aesdev "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/aesdev.rs"
click node_simd "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/simd.rs"
click node_macho "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/macho.rs"
click node_decode "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-xlat/src/decode.rs"
click node_translate "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-xlat/src/trans.rs"
click node_run "https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-xlat/src/run.rs"

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_media_cli,node_feed_download,node_archive,node_im4p,node_aea,node_apfs,node_dsc toneBlue
class node_setup_ui,node_installer,node_disk,node_usb toneAmber
class node_boot_menu,node_inventory,node_readiness,node_bringup,node_apic,node_nvme,node_macboot,node_exfat toneMint
class node_runtime_entry,node_machine,node_memory,node_mmu,node_gic,node_rt_pci,node_aesdev,node_simd,node_macho toneRose
class node_decode,node_translate,node_run,node_user,node_ipsw,node_host toneIndigo
```

## Components

### Media tooling

- [IPSW tools](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/main.rs): `crates/anathema-media/src/main.rs`
- [Feed and download](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/download.rs): `crates/anathema-media/src/download.rs`
- [ZIP and plist](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/zip.rs): `crates/anathema-media/src/zip.rs`
- [IM4P unwrap](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/im4p.rs): `crates/anathema-media/src/im4p.rs`
- [AEA decrypt](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/aea.rs): `crates/anathema-media/src/aea.rs`
- [APFS reader](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/apfs.rs): `crates/anathema-media/src/apfs.rs`
- [dyld cache reader](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-media/src/dsc.rs): `crates/anathema-media/src/dsc.rs`

### USB installer

- [Installer UI](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-setup/src/main.rs): `crates/anathema-setup/src/main.rs`
- [Disk installer](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-setup/src/install.rs): `crates/anathema-setup/src/install.rs`
- [Disk operations](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-setup/src/disk.rs): `crates/anathema-setup/src/disk.rs`

### UEFI loader

- [UEFI menu](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/main.rs): `crates/anathema-boot/src/main.rs`
- [Hardware inventory](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/report.rs): `crates/anathema-boot/src/report.rs`
- [Readiness check](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/readiness.rs): `crates/anathema-boot/src/readiness.rs`
- [Hardware bring-up](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/bringup/mod.rs): `crates/anathema-boot/src/bringup/mod.rs`
- [APIC and SMP](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/bringup/apic.rs): `crates/anathema-boot/src/bringup/apic.rs`
- [NVMe and GPT](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/bringup/nvme.rs): `crates/anathema-boot/src/bringup/nvme.rs`
- [macOS loader](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/macboot.rs): `crates/anathema-boot/src/macboot.rs`
- [exFAT reader](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-boot/src/exfat.rs): `crates/anathema-boot/src/exfat.rs`

### Virtual machine

- [Runtime harness](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/main.rs): `crates/anathema-rt/src/main.rs`
- [ARM machine](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/machine.rs): `crates/anathema-rt/src/machine.rs`
- [RAM and bus](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/mem.rs): `crates/anathema-rt/src/mem.rs`
- [Software MMU](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/mmu.rs): `crates/anathema-rt/src/mmu.rs`
- [GICv3](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/gic.rs): `crates/anathema-rt/src/gic.rs`
- [PCIe virtio](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/pci.rs): `crates/anathema-rt/src/pci.rs`
- [AES device](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/aesdev.rs): `crates/anathema-rt/src/aesdev.rs`
- [SIMD fallbacks](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/simd.rs): `crates/anathema-rt/src/simd.rs`
- [Mach-O loader](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-rt/src/macho.rs): `crates/anathema-rt/src/macho.rs`

### Instruction translation

- [AArch64 decoder](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-xlat/src/decode.rs): `crates/anathema-xlat/src/decode.rs`
- [x86 emitter](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-xlat/src/trans.rs): `crates/anathema-xlat/src/trans.rs`
- [Block runner](https://github.com/riftaway7-code/anathema/blob/main/crates/anathema-xlat/src/run.rs): `crates/anathema-xlat/src/run.rs`

### Other components

- **Operator**
- **macOS IPSW**
- **USB stick**
- **x86-64 host**

## Connections

- Operator → IPSW tools: prepares media (evidence: `README.md`)
- macOS IPSW → IPSW tools: provides image (evidence: `README.md`)
- IPSW tools → Feed and download: uses (evidence: `README.md`)
- IPSW tools → ZIP and plist: unpacks (evidence: `README.md`)
- IPSW tools → IM4P unwrap: unwraps (evidence: `README.md`)
- IPSW tools → AEA decrypt: decrypts (evidence: `README.md`)
- IPSW tools → APFS reader: reads (evidence: `README.md`)
- IPSW tools → dyld cache reader: reads (evidence: `README.md`)
- Operator → Installer UI: starts installation (evidence: `README.md`)
- Installer UI → Disk installer: starts install (evidence: `crates/anathema-setup/src/main.rs`)
- Disk installer → Disk operations: writes drive (evidence: `crates/anathema-setup/src/install.rs`)
- Disk installer → USB stick: prepares (evidence: `README.md`)
- USB stick → UEFI menu: boots (evidence: `README.md`)
- x86-64 host → UEFI menu: starts UEFI app (evidence: `README.md`)
- UEFI menu → Hardware inventory: collects report (evidence: `crates/anathema-boot/src/main.rs`)
- Hardware inventory → Readiness check: supplies inventory (evidence: `crates/anathema-boot/src/main.rs`)
- UEFI menu → Hardware bring-up: runs test (evidence: `crates/anathema-boot/src/main.rs`)
- Hardware bring-up → APIC and SMP: uses (evidence: `crates/anathema-boot/src/bringup/mod.rs`)
- Hardware bring-up → NVMe and GPT: uses (evidence: `crates/anathema-boot/src/bringup/mod.rs`)
- UEFI menu → macOS loader: dispatches boot (evidence: `crates/anathema-boot/src/main.rs`)
- macOS loader → exFAT reader: reads RAM disk (evidence: `README.md`)
- macOS loader → Runtime harness: runs runtime (evidence: `README.md`)
- Runtime harness → Mach-O loader: loads kernel image (evidence: `crates/anathema-rt/src/main.rs`)
- Runtime harness → ARM machine: executes guest (evidence: `crates/anathema-rt/src/main.rs`)
- ARM machine → RAM and bus: accesses memory bus (evidence: `crates/anathema-rt/src/machine.rs`)
- ARM machine → Software MMU: translates addresses (evidence: `crates/anathema-rt/src/machine.rs`)
- ARM machine → AES device: dispatches device I/O (evidence: `crates/anathema-rt/src/machine.rs`)
- ARM machine → PCIe virtio: dispatches PCI I/O (evidence: `crates/anathema-rt/src/machine.rs`)
- RAM and bus → GICv3: routes register access (evidence: `crates/anathema-rt/src/mem.rs`)
- RAM and bus → AES device: backs device DMA (evidence: `crates/anathema-rt/src/aesdev.rs`)
- RAM and bus → PCIe virtio: backs device access (evidence: `crates/anathema-rt/src/pci.rs`)
- ARM machine → SIMD fallbacks: uses fallbacks (evidence: `README.md`)
- ARM machine → Block runner: runs translated blocks (evidence: `README.md`)
- Block runner → x86 emitter: requests translation (evidence: `README.md`)
- x86 emitter → AArch64 decoder: decodes instructions (evidence: `crates/anathema-xlat/src/trans.rs`)
