# danbyumagic/gbrunch architecture

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

- Interactive diagram: https://gitdiagram.com/danbyumagic/gbrunch
- Repository: https://github.com/danbyumagic/gbrunch

## Overview

GBRUNCH builds a local, recovery-derived Googlebook OS compatibility image and deploys it to an external USB trial or, experimentally, an internal dual-boot layout. The user-facing loop begins in the Linux toolbox: prepare the official recovery, build locally, trial-boot the result, then return to collect diagnostics. Separate capabilities cover toolbox persistence, SSD/userdata maintenance, QEMU research and AMD graphics investigation. The README documents the broad workflow; source excerpts show selected assembly, install and storage calls, so unsampled subsystem links are omitted where their wiring is not established.

Main entry points: [`tools/dualboot_installer.py`](https://github.com/danbyumagic/gbrunch/blob/main/tools/dualboot_installer.py) (Internal installer), [`tools/inspect_recovery.py`](https://github.com/danbyumagic/gbrunch/blob/main/tools/inspect_recovery.py) (Recovery inspection), [`toolkit/live/root/opt/gbrunch/trial.py`](https://github.com/danbyumagic/gbrunch/blob/main/toolkit/live/root/opt/gbrunch/trial.py) (USB trial deployment), [`tools/assemble_native_android.py`](https://github.com/danbyumagic/gbrunch/blob/main/tools/assemble_native_android.py) (Compatibility image assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_toolbox["Linux Toolbox"]
  node_dashboard["Toolbox desktop<br/>[dashboard.py]"]
  node_workspace[("Persistent workspace<br/>[storage.py]")]
end

subgraph group_image["Image Preparation"]
  node_recovery["Recovery inspection"]
  node_image_builder["Compatibility image assembly"]
  node_external_image["QEMU lab assembly"]
  node_compat_probe["Compatibility probe"]
end

subgraph group_deployment["Deployment and Boot"]
  node_trial["USB trial deployment<br/>[trial.py]"]
  node_installer["Internal installer"]
  node_boot_menu["Googlebook boot menu"]
end

subgraph group_support["Diagnostics and Maintenance"]
  node_report["Hardware reports<br/>[report.py]"]
  node_userdata["Userdata maintenance"]
  node_ssd_maintenance["External SSD maintenance"]
end

subgraph group_research["Research Integrations"]
  node_amd_preflight["AMD source preflight"]
  node_amd_provenance["AMD source provenance"]
  node_vm_launcher["Windows VM launcher<br/>[launch.py]"]
  node_vm_manifest["VM asset manifest<br/>[make_manifest.py]"]
end

node_user(("Laptop user"))
node_googlebook(("Googlebook OS"))

node_user -->|"uses"| node_dashboard
node_dashboard -.->|"starts recovery prep"| node_recovery
node_recovery -->|"inspects recovery"| node_image_builder
node_user -->|"prepares image"| node_image_builder
node_image_builder -->|"produces local image"| node_googlebook
node_user -->|"requests USB trial"| node_trial
node_trial -->|"uses workspace"| node_workspace
node_trial -->|"calls deployment helpers"| node_installer
node_trial -->|"deploys trial for boot"| node_googlebook
node_user -->|"requests internal install"| node_installer
node_installer -->|"imports GPT reader"| node_recovery
node_installer -->|"renders boot menu"| node_boot_menu
node_installer -->|"installs boot path"| node_googlebook
node_user -->|"collects logs"| node_report
node_user -->|"maintains SSD"| node_ssd_maintenance
node_ssd_maintenance -.->|"runs isolated maintenance"| node_userdata
node_external_image -->|"imports GPT reader"| node_recovery
node_user -.->|"runs VM probe"| node_compat_probe
node_compat_probe -->|"imports GPT reader"| node_recovery
node_user -->|"investigates AMD"| node_amd_preflight
node_amd_preflight -.->|"uses provenance checks"| node_amd_provenance
node_vm_manifest -->|"imports launcher helper"| node_vm_launcher

click node_dashboard "https://github.com/danbyumagic/gbrunch/blob/main/toolkit/live/root/opt/gbrunch/dashboard.py"
click node_workspace "https://github.com/danbyumagic/gbrunch/blob/main/toolkit/live/root/opt/gbrunch/storage.py"
click node_recovery "https://github.com/danbyumagic/gbrunch/blob/main/tools/inspect_recovery.py"
click node_image_builder "https://github.com/danbyumagic/gbrunch/blob/main/tools/assemble_native_android.py"
click node_external_image "https://github.com/danbyumagic/gbrunch/blob/main/tools/assemble_external_lab.py"
click node_compat_probe "https://github.com/danbyumagic/gbrunch/blob/main/tools/build_compat_probe.py"
click node_trial "https://github.com/danbyumagic/gbrunch/blob/main/toolkit/live/root/opt/gbrunch/trial.py"
click node_installer "https://github.com/danbyumagic/gbrunch/blob/main/tools/dualboot_installer.py"
click node_boot_menu "https://github.com/danbyumagic/gbrunch/blob/main/tools/googlebook_boot_menu.py"
click node_report "https://github.com/danbyumagic/gbrunch/blob/main/toolkit/live/root/opt/gbrunch/report.py"
click node_userdata "https://github.com/danbyumagic/gbrunch/blob/main/tools/maintain_userdata_guest.py"
click node_ssd_maintenance "https://github.com/danbyumagic/gbrunch/blob/main/tools/maintain_external_ssd_macos.py"
click node_amd_preflight "https://github.com/danbyumagic/gbrunch/blob/main/tools/build_amd_kernel_modules.py"
click node_amd_provenance "https://github.com/danbyumagic/gbrunch/blob/main/tools/amd_source_provenance.py"
click node_vm_launcher "https://github.com/danbyumagic/gbrunch/blob/main/vm/windows/launch.py"
click node_vm_manifest "https://github.com/danbyumagic/gbrunch/blob/main/vm/windows/make_manifest.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_dashboard,node_workspace,node_user toneBlue
class node_recovery,node_image_builder,node_external_image,node_compat_probe toneAmber
class node_trial,node_installer,node_boot_menu toneMint
class node_report,node_userdata,node_ssd_maintenance toneRose
class node_amd_preflight,node_amd_provenance,node_vm_launcher,node_vm_manifest,node_googlebook toneIndigo
```

## Components

### Linux Toolbox

- [Toolbox desktop](https://github.com/danbyumagic/gbrunch/blob/main/toolkit/live/root/opt/gbrunch/dashboard.py): `toolkit/live/root/opt/gbrunch/dashboard.py`
- [Persistent workspace](https://github.com/danbyumagic/gbrunch/blob/main/toolkit/live/root/opt/gbrunch/storage.py): `toolkit/live/root/opt/gbrunch/storage.py`

### Image Preparation

- [Recovery inspection](https://github.com/danbyumagic/gbrunch/blob/main/tools/inspect_recovery.py): `tools/inspect_recovery.py`
- [Compatibility image assembly](https://github.com/danbyumagic/gbrunch/blob/main/tools/assemble_native_android.py): `tools/assemble_native_android.py`
- [QEMU lab assembly](https://github.com/danbyumagic/gbrunch/blob/main/tools/assemble_external_lab.py): `tools/assemble_external_lab.py`
- [Compatibility probe](https://github.com/danbyumagic/gbrunch/blob/main/tools/build_compat_probe.py): `tools/build_compat_probe.py`

### Deployment and Boot

- [USB trial deployment](https://github.com/danbyumagic/gbrunch/blob/main/toolkit/live/root/opt/gbrunch/trial.py): `toolkit/live/root/opt/gbrunch/trial.py`
- [Internal installer](https://github.com/danbyumagic/gbrunch/blob/main/tools/dualboot_installer.py): `tools/dualboot_installer.py`
- [Googlebook boot menu](https://github.com/danbyumagic/gbrunch/blob/main/tools/googlebook_boot_menu.py): `tools/googlebook_boot_menu.py`

### Diagnostics and Maintenance

- [Hardware reports](https://github.com/danbyumagic/gbrunch/blob/main/toolkit/live/root/opt/gbrunch/report.py): `toolkit/live/root/opt/gbrunch/report.py`
- [Userdata maintenance](https://github.com/danbyumagic/gbrunch/blob/main/tools/maintain_userdata_guest.py): `tools/maintain_userdata_guest.py`
- [External SSD maintenance](https://github.com/danbyumagic/gbrunch/blob/main/tools/maintain_external_ssd_macos.py): `tools/maintain_external_ssd_macos.py`

### Research Integrations

- [AMD source preflight](https://github.com/danbyumagic/gbrunch/blob/main/tools/build_amd_kernel_modules.py): `tools/build_amd_kernel_modules.py`
- [AMD source provenance](https://github.com/danbyumagic/gbrunch/blob/main/tools/amd_source_provenance.py): `tools/amd_source_provenance.py`
- [Windows VM launcher](https://github.com/danbyumagic/gbrunch/blob/main/vm/windows/launch.py): `vm/windows/launch.py`
- [VM asset manifest](https://github.com/danbyumagic/gbrunch/blob/main/vm/windows/make_manifest.py): `vm/windows/make_manifest.py`

### Other components

- **Laptop user**
- **Googlebook OS**

## Connections

- Laptop user → Toolbox desktop: uses (evidence: `README.md`)
- Toolbox desktop → Recovery inspection: starts recovery prep
- Recovery inspection → Compatibility image assembly: inspects recovery (evidence: `tools/assemble_native_android.py`)
- Laptop user → Compatibility image assembly: prepares image (evidence: `README.md`)
- Compatibility image assembly → Googlebook OS: produces local image (evidence: `README.md`)
- Laptop user → USB trial deployment: requests USB trial (evidence: `README.md`)
- USB trial deployment → Persistent workspace: uses workspace (evidence: `toolkit/live/root/opt/gbrunch/trial.py`)
- USB trial deployment → Internal installer: calls deployment helpers (evidence: `toolkit/live/root/opt/gbrunch/trial.py`)
- USB trial deployment → Googlebook OS: deploys trial for boot (evidence: `README.md`)
- Laptop user → Internal installer: requests internal install (evidence: `README.md`)
- Internal installer → Recovery inspection: imports GPT reader (evidence: `tools/dualboot_installer.py`)
- Internal installer → Googlebook boot menu: renders boot menu (evidence: `tools/dualboot_installer.py`)
- Internal installer → Googlebook OS: installs boot path (evidence: `README.md`)
- Laptop user → Hardware reports: collects logs (evidence: `README.md`)
- Laptop user → External SSD maintenance: maintains SSD (evidence: `README.md`)
- External SSD maintenance → Userdata maintenance: runs isolated maintenance
- QEMU lab assembly → Recovery inspection: imports GPT reader (evidence: `tools/assemble_external_lab.py`)
- Laptop user → Compatibility probe: runs VM probe
- Compatibility probe → Recovery inspection: imports GPT reader (evidence: `tools/build_compat_probe.py`)
- Laptop user → AMD source preflight: investigates AMD (evidence: `README.md`)
- AMD source preflight → AMD source provenance: uses provenance checks
- VM asset manifest → Windows VM launcher: imports launcher helper (evidence: `vm/windows/make_manifest.py`)