# deedone/highheat architecture

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

- Interactive diagram: https://gitdiagram.com/deedone/highheat
- Repository: https://github.com/deedone/highheat

## Overview

1. **What this repo is**
   HighHeat is a command-line tool that sits on top of an existing Yocto or Moulin workspace and accelerates the inner development loop. It does not replace BitBake; instead, it finds the already-built project, runs the relevant compile/install/deploy steps directly in the workdir, and pushes the result to a target.

2. **Top-level orchestration**
   The entry point is `src/highheat/main.py`, which likely parses the `hh` CLI and dispatches commands such as `edit`, `build`, `deploy`, `build-deploy`, `info`, and `editimg`. This is the central controller that ties together project discovery, image handling, transport, and command execution.

3. **Project discovery and abstraction layer**
   The `project.py` family is the core domain model for “what project am I working on?” It appears to encapsulate Yocto/Moulin project metadata, work directories, source directories, deploy artifacts, and recipe mapping. The variants:
   - `project_linux.py` for Linux/kernel-specific handling
   - `project_xen.py` for Xen-related handling
   - `project_interactive.py` for interactive image editing workflows
   suggest that the system adapts its behavior based on project type rather than using one generic build path.

4. **Yocto integration**
   `yocto.py` and `bbdata.py` are the repository’s bridge into BitBake-generated state. HighHeat likely reads existing metadata and filesystem layout from the Yocto build tree, rather than invoking BitBake for dependency resolution. This is the boundary that makes the tool fast: it depends on prior BitBake output but avoids BitBake during iterative edits.

5. **Build and shell execution**
   `shell.py` and `moulin_helpers.py` are the execution layer for local shell commands and environment-specific command generation. The README’s confirmation and dry-run behavior implies this layer centralizes command construction, prompting, and execution. This is the main trust boundary: HighHeat shells out to build, install, deploy, mount, unpack, and repack commands on the host.

6. **Target transport**
   `transport.py` and `transport_rsync.py` represent the delivery path from workstation to target. The repo supports both local and remote targets, and the dedicated rsync transport suggests file synchronization is a first-class mechanism for deployment. This layer isolates “how bytes get to the target” from the project and image logic.

7. **Image handling subsystem**
   `image.py` is the abstraction over target image formats, with format-specific implementations in:
   - `image_ext4.py`
   - `image_ramfs_gz.py`
   - `image_uimage.py`
   - `image_dtb.py`
   This is a major architectural boundary: HighHeat treats “deploy target” as either a directory or a packaged image, and selects unpack/edit/repack behavior based on the image type.

8. **Interactive image editing**
   `project_interactive.py` and the `editimg` command support a higher-touch workflow: download an image, unpack or mount it, allow manual edits, then write it back. The README shows this for initramfs and DTB files, so the workflow includes both filesystem-style images and single binary artifacts. DTB handling is especially specialized because decompilation/recompilation is used to preserve editable structure.

9. **Configuration and runtime behavior**
   `config.py` and `log.py` handle user preferences and diagnostics. The config file controls editor choice, interactive editor behavior, confirmation prompts, download cache location, cleanup interval, and gzip compression level. Logging and verbosity are runtime concerns that influence nearly every subsystem but do not change the core architecture.

10. **External environment and assumptions**
   HighHeat is built around a pre-existing Yocto or Moulin workspace and assumes the project has already been built at least once with BitBake. It is designed to run from inside the workspace root so it can autodetect the current project and domain. That means the architecture depends heavily on filesystem layout and BitBake output conventions, not on a long-running service or database.

11. **Main data flows**
   The most important flow is:
   source/workdir discovery -> local build action -> artifact selection -> transport -> target update.
   A second major flow is:
   remote/local image acquisition -> unpack/mount/decompile -> interactive edit -> repack -> redeploy.
   These flows show that HighHeat is primarily a file- and shell-orchestration tool, with no persistent backend.

12. **Key boundaries to draw in an architecture diagram**
   The diagram should clearly separate:
   - the CLI/controller layer
   - project/Yocto metadata resolution
   - build and shell execution on the host
   - image-format-specific unpack/edit/repack logic
   - transport to local or remote targets
   - the target filesystem/image itself
   The important architectural point is that HighHeat does not own the build system or the target image lifecycle; it orchestrates around them.

Main entry points: [`src/highheat/project.py`](https://github.com/deedone/highheat/blob/master/src/highheat/project.py) (Project), [`src/highheat/main.py`](https://github.com/deedone/highheat/blob/master/src/highheat/main.py) (hh CLI), [`src/highheat/image.py`](https://github.com/deedone/highheat/blob/master/src/highheat/image.py) (Image core), [`src/highheat/project_interactive.py`](https://github.com/deedone/highheat/blob/master/src/highheat/project_interactive.py) (Interactive)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & control"]
  node_main["hh CLI<br/>entrypoint<br/>[main.py]"]
  node_config["Config<br/>[config.py]"]
  node_log["Logging<br/>diagnostics<br/>[log.py]"]
end

subgraph group_project["Project model"]
  node_project["Project<br/>workspace model<br/>[project.py]"]
  node_project_linux["Linux proj<br/>project variant<br/>[project_linux.py]"]
  node_project_xen["Xen proj<br/>project variant<br/>[project_xen.py]"]
  node_project_interactive["Interactive<br/>workflow variant"]
  node_yocto["Yocto bridge<br/>workspace integration<br/>[yocto.py]"]
  node_bbdata["BitBake data<br/>metadata reader<br/>[bbdata.py]"]
end

subgraph group_build["Host execution"]
  node_shell["Shell exec<br/>command runner<br/>[shell.py]"]
  node_moulin_helpers["Moulin helpers<br/>env helpers<br/>[moulin_helpers.py]"]
end

subgraph group_image["Image handling"]
  node_image["Image core<br/>image abstraction<br/>[image.py]"]
  node_image_ext4["ext4<br/>image format<br/>[image_ext4.py]"]
  node_image_ramfs_gz["ramfs.gz<br/>image format<br/>[image_ramfs_gz.py]"]
  node_image_uimage["uImage<br/>image format<br/>[image_uimage.py]"]
  node_image_dtb["DTB<br/>image format<br/>[image_dtb.py]"]
end

subgraph group_deploy["Deployment"]
  node_transport["Transport<br/>delivery abstraction<br/>[transport.py]"]
  node_transport_rsync["rsync<br/>transport impl<br/>[transport_rsync.py]"]
end

node_main -->|"reads"| node_config
node_main -->|"uses"| node_log
node_main -->|"dispatches"| node_project
node_main -->|"editimg"| node_project_interactive
node_project -->|"discovers"| node_yocto
node_yocto -->|"reads"| node_bbdata
node_project -->|"specializes"| node_project_linux
node_project -->|"specializes"| node_project_xen
node_project -->|"specializes"| node_project_interactive
node_project -->|"executes"| node_shell
node_shell -->|"builds"| node_moulin_helpers
node_main -->|"manages"| node_image
node_image -->|"implements"| node_image_ext4
node_image -->|"implements"| node_image_ramfs_gz
node_image -->|"implements"| node_image_uimage
node_image -->|"implements"| node_image_dtb
node_main -->|"deploys via"| node_transport
node_transport -->|"implements"| node_transport_rsync
node_project -->|"targets"| node_transport
node_project_interactive -->|"edits"| node_image

click node_main "https://github.com/deedone/highheat/blob/master/src/highheat/main.py"
click node_config "https://github.com/deedone/highheat/blob/master/src/highheat/config.py"
click node_log "https://github.com/deedone/highheat/blob/master/src/highheat/log.py"
click node_project "https://github.com/deedone/highheat/blob/master/src/highheat/project.py"
click node_project_linux "https://github.com/deedone/highheat/blob/master/src/highheat/project_linux.py"
click node_project_xen "https://github.com/deedone/highheat/blob/master/src/highheat/project_xen.py"
click node_project_interactive "https://github.com/deedone/highheat/blob/master/src/highheat/project_interactive.py"
click node_yocto "https://github.com/deedone/highheat/blob/master/src/highheat/yocto.py"
click node_bbdata "https://github.com/deedone/highheat/blob/master/src/highheat/bbdata.py"
click node_shell "https://github.com/deedone/highheat/blob/master/src/highheat/shell.py"
click node_moulin_helpers "https://github.com/deedone/highheat/blob/master/src/highheat/moulin_helpers.py"
click node_image "https://github.com/deedone/highheat/blob/master/src/highheat/image.py"
click node_image_ext4 "https://github.com/deedone/highheat/blob/master/src/highheat/image_ext4.py"
click node_image_ramfs_gz "https://github.com/deedone/highheat/blob/master/src/highheat/image_ramfs_gz.py"
click node_image_uimage "https://github.com/deedone/highheat/blob/master/src/highheat/image_uimage.py"
click node_image_dtb "https://github.com/deedone/highheat/blob/master/src/highheat/image_dtb.py"
click node_transport "https://github.com/deedone/highheat/blob/master/src/highheat/transport.py"
click node_transport_rsync "https://github.com/deedone/highheat/blob/master/src/highheat/transport_rsync.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_main,node_config,node_log toneBlue
class node_project,node_project_linux,node_project_xen,node_project_interactive,node_yocto,node_bbdata toneAmber
class node_shell,node_moulin_helpers toneMint
class node_image,node_image_ext4,node_image_ramfs_gz,node_image_uimage,node_image_dtb toneRose
class node_transport,node_transport_rsync toneIndigo
```

## Components

### CLI & control

Command entrypoints and user-facing orchestration

- [hh CLI](https://github.com/deedone/highheat/blob/master/src/highheat/main.py): entrypoint · Parses commands and routes high-level workflows. · `src/highheat/main.py`
- [Config](https://github.com/deedone/highheat/blob/master/src/highheat/config.py): runtime config · User preferences and behavior flags. · `src/highheat/config.py`
- [Logging](https://github.com/deedone/highheat/blob/master/src/highheat/log.py): diagnostics · Verbosity and runtime diagnostics. · `src/highheat/log.py`

### Project model

Workspace discovery and project-specific behavior

- [Project](https://github.com/deedone/highheat/blob/master/src/highheat/project.py): workspace model · Core abstraction for the active Yocto/Moulin workspace and artifacts. · `src/highheat/project.py`
- [Linux proj](https://github.com/deedone/highheat/blob/master/src/highheat/project_linux.py): project variant · Kernel/Linux-specific project handling. · `src/highheat/project_linux.py`
- [Xen proj](https://github.com/deedone/highheat/blob/master/src/highheat/project_xen.py): project variant · Xen-specific project handling. · `src/highheat/project_xen.py`
- [Interactive](https://github.com/deedone/highheat/blob/master/src/highheat/project_interactive.py): workflow variant · Interactive image editing workflow and project adaptation. · `src/highheat/project_interactive.py`
- [Yocto bridge](https://github.com/deedone/highheat/blob/master/src/highheat/yocto.py): workspace integration · Reads Yocto workspace conventions and build-tree state. · `src/highheat/yocto.py`
- [BitBake data](https://github.com/deedone/highheat/blob/master/src/highheat/bbdata.py): metadata reader · Consumes BitBake-generated metadata and filesystem layout. · `src/highheat/bbdata.py`

### Host execution

Local shell execution and BitBake-derived state

- [Shell exec](https://github.com/deedone/highheat/blob/master/src/highheat/shell.py): command runner · Runs local host commands for build, install, mount, and repack steps. · `src/highheat/shell.py`
- [Moulin helpers](https://github.com/deedone/highheat/blob/master/src/highheat/moulin_helpers.py): env helpers · Builds environment-specific commands and shell snippets. · `src/highheat/moulin_helpers.py`

### Image handling

Format-specific unpack/edit/repack logic

- [Image core](https://github.com/deedone/highheat/blob/master/src/highheat/image.py): image abstraction · Chooses image handling behavior by artifact type. · `src/highheat/image.py`
- [ext4](https://github.com/deedone/highheat/blob/master/src/highheat/image_ext4.py): image format · Filesystem image unpack/edit/repack support. · `src/highheat/image_ext4.py`
- [ramfs.gz](https://github.com/deedone/highheat/blob/master/src/highheat/image_ramfs_gz.py): image format · Compressed initramfs handling. · `src/highheat/image_ramfs_gz.py`
- [uImage](https://github.com/deedone/highheat/blob/master/src/highheat/image_uimage.py): image format · U-Boot image handling. · `src/highheat/image_uimage.py`
- [DTB](https://github.com/deedone/highheat/blob/master/src/highheat/image_dtb.py): image format · Device tree decompile/edit/recompile workflow. · `src/highheat/image_dtb.py`

### Deployment

Artifact transfer to local or remote targets

- [Transport](https://github.com/deedone/highheat/blob/master/src/highheat/transport.py): delivery abstraction · Moves artifacts to local or remote targets. · `src/highheat/transport.py`
- [rsync](https://github.com/deedone/highheat/blob/master/src/highheat/transport_rsync.py): transport impl · File synchronization transport implementation. · `src/highheat/transport_rsync.py`

## Connections

- hh CLI → Config: reads · Loads user and runtime settings.
- hh CLI → Logging: uses · Initializes diagnostics and verbosity.
- hh CLI → Project: dispatches · Routes commands through the active project model.
- hh CLI → Interactive: editimg · Invokes interactive image editing flow.
- Project → Yocto bridge: discovers · Finds workspace and build-tree state.
- Yocto bridge → BitBake data: reads · Consumes BitBake-generated metadata.
- Project → Linux proj: specializes · Applies Linux-specific behavior.
- Project → Xen proj: specializes · Applies Xen-specific behavior.
- Project → Interactive: specializes · Enables interactive image workflows.
- Project → Shell exec: executes · Runs host-side build and filesystem commands.
- Shell exec → Moulin helpers: builds · Generates environment-specific shell actions.
- hh CLI → Image core: manages · Selects image-specific operations.
- Image core → ext4: implements · Filesystem image support.
- Image core → ramfs.gz: implements · Compressed ramfs support.
- Image core → uImage: implements · U-Boot image support.
- Image core → DTB: implements · DTB handling support.
- hh CLI → Transport: deploys via · Sends artifacts to targets.
- Transport → rsync: implements · Rsync-based synchronization.
- Project → Transport: targets · Uses transport for local or remote updates.
- Interactive → Image core: edits · Downloads, unpacks, edits, and repacks images.