# devpryan7792/kurogane architecture

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

- Interactive diagram: https://gitdiagram.com/devpryan7792/kurogane
- Repository: https://github.com/devpryan7792/kurogane

## Overview

KUROGANE compiles declarative appliance recipes into immutable EROFS arcade boards, then supports testing, multi-appliance disk composition, USB flashing, and boot-time appliance launch. The recipe-to-image and CLI dispatch relationships are supported by the README and sampled source; some boot/runtime details are documented but their exact internal wiring was not sampled.

Main entry points: [`src/kurogane/cli.py`](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/cli.py) (Kurogane CLI), [`src/kurogane/composer.py`](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/composer.py) (Disk Composer), [`src/kurogane/flasher.py`](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/flasher.py) (Safe Flasher), [`stages`](https://github.com/devpryan7792/kurogane/tree/main/stages) (Boot Stages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Recipes and Configuration"]
  node_recipes["Appliance Recipes"]
  node_schema["Recipe Schema<br/>[schema.py]"]
  node_yaml["YAML Parser<br/>[yaml.py]"]
end

subgraph group_image["Image Production"]
  node_cli["Kurogane CLI<br/>[cli.py]"]
  node_builder["Cartridge Builder<br/>[builder.py]"]
  node_cartridge["EROFS Cartridge"]
  node_composer["Disk Composer<br/>[composer.py]"]
  node_disk["Bootable Disk Image"]
end

subgraph group_delivery["Testing and Delivery"]
  node_runner["QEMU Runner<br/>[runner.py]"]
  node_qemu["QEMU"]
  node_flasher["Safe Flasher<br/>[flasher.py]"]
  node_usb[("USB Device")]
end

subgraph group_boot["Boot and Appliance Runtime"]
  node_bootloader["UEFI Boot Menu<br/>[composer.py]"]
  node_hub["Hub Loader<br/>[hub_loader.sh]"]
  node_initramfs["Initramfs Hook"]
  node_stages["Boot Stages"]
  node_data[("Persistent User Data<br/>[30-storage.sh]")]
  node_launchers["App Launchers"]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_cli
node_recipes -->|"parsed by"| node_yaml
node_yaml -->|"validates against"| node_schema
node_cli -->|"build dispatch"| node_builder
node_builder -->|"compiles"| node_cartridge
node_cli -->|"compose dispatch"| node_composer
node_composer -->|"reads"| node_cartridge
node_composer -->|"assembles"| node_disk
node_cli -->|"run dispatch"| node_runner
node_runner -->|"launches"| node_qemu
node_cli -->|"flash dispatch"| node_flasher
node_flasher -->|"composes image"| node_composer
node_flasher -->|"writes image"| node_usb
node_disk -->|"boots through"| node_bootloader
node_bootloader -->|"selects appliance"| node_hub
node_hub -->|"uses hook"| node_initramfs
node_initramfs -->|"starts runtime"| node_stages
node_stages -->|"mounts"| node_data
node_stages -->|"starts apps"| node_launchers

click node_recipes "https://github.com/devpryan7792/kurogane/tree/main/recipes"
click node_schema "https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/schema.py"
click node_yaml "https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/yaml.py"
click node_cli "https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/cli.py"
click node_builder "https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/builder.py"
click node_composer "https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/composer.py"
click node_runner "https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/runner.py"
click node_flasher "https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/flasher.py"
click node_bootloader "https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/composer.py"
click node_hub "https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/hub_loader.sh"
click node_initramfs "https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/initcpio/hooks/cartilage_hub"
click node_stages "https://github.com/devpryan7792/kurogane/tree/main/stages"
click node_data "https://github.com/devpryan7792/kurogane/blob/main/stages/30-storage.sh"
click node_launchers "https://github.com/devpryan7792/kurogane/tree/main/launchers"

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_recipes,node_schema,node_yaml toneBlue
class node_cli,node_builder,node_cartridge,node_composer,node_disk toneAmber
class node_runner,node_qemu,node_flasher,node_usb toneMint
class node_bootloader,node_hub,node_initramfs,node_stages,node_data,node_launchers toneRose
class node_operator toneIndigo
```

## Components

### Recipes and Configuration

- [Appliance Recipes](https://github.com/devpryan7792/kurogane/tree/main/recipes): `recipes`
- [Recipe Schema](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/schema.py): `src/kurogane/schema.py`
- [YAML Parser](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/yaml.py): `src/kurogane/yaml.py`

### Image Production

- [Kurogane CLI](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/cli.py): `src/kurogane/cli.py`
- [Cartridge Builder](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/builder.py): `src/kurogane/builder.py`
- **EROFS Cartridge**
- [Disk Composer](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/composer.py): `src/kurogane/composer.py`
- **Bootable Disk Image**

### Testing and Delivery

- [QEMU Runner](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/runner.py): `src/kurogane/runner.py`
- **QEMU**
- [Safe Flasher](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/flasher.py): `src/kurogane/flasher.py`
- **USB Device**

### Boot and Appliance Runtime

- [UEFI Boot Menu](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/composer.py): `src/kurogane/composer.py`
- [Hub Loader](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/hub_loader.sh): `src/kurogane/hub_loader.sh`
- [Initramfs Hook](https://github.com/devpryan7792/kurogane/blob/main/src/kurogane/initcpio/hooks/cartilage_hub): `src/kurogane/initcpio/hooks/cartilage_hub`
- [Boot Stages](https://github.com/devpryan7792/kurogane/tree/main/stages): `stages`
- [Persistent User Data](https://github.com/devpryan7792/kurogane/blob/main/stages/30-storage.sh): `stages/30-storage.sh`
- [App Launchers](https://github.com/devpryan7792/kurogane/tree/main/launchers): `launchers`

### Other components

- **Operator**

## Connections

- Operator → Kurogane CLI: invokes
- Appliance Recipes → YAML Parser: parsed by
- YAML Parser → Recipe Schema: validates against
- Kurogane CLI → Cartridge Builder: build dispatch
- Cartridge Builder → EROFS Cartridge: compiles
- Kurogane CLI → Disk Composer: compose dispatch
- Disk Composer → EROFS Cartridge: reads
- Disk Composer → Bootable Disk Image: assembles
- Kurogane CLI → QEMU Runner: run dispatch
- QEMU Runner → QEMU: launches
- Kurogane CLI → Safe Flasher: flash dispatch
- Safe Flasher → Disk Composer: composes image
- Safe Flasher → USB Device: writes image
- Bootable Disk Image → UEFI Boot Menu: boots through
- UEFI Boot Menu → Hub Loader: selects appliance
- Hub Loader → Initramfs Hook: uses hook
- Initramfs Hook → Boot Stages: starts runtime
- Boot Stages → Persistent User Data: mounts
- Boot Stages → App Launchers: starts apps