# projectbluefin/utah architecture

> Architecture diagram of the GitHub repository projectbluefin/utah, 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/projectbluefin/utah
- Repository: https://github.com/projectbluefin/utah

## Overview

Utahraptor composes a Bluefin desktop image on Fedora Hummingbird, then packages it into live media whose bootc-installer can install the embedded image to an encrypted disk offline. The core stages are package-contract resolution, desktop/image composition, and live installation; the status page is a supporting user-facing capability. README claims establish the factory OCI input and end-to-end ISO workflow, while sampled source confirms package resolution and status-page data/API behavior. Some build-recipe wiring is unsampled, so uncertain call edges are omitted.

Main entry points: [`Containerfile`](https://github.com/projectbluefin/utah/blob/main/Containerfile) (Image recipe), [`scripts/install-packages.py`](https://github.com/projectbluefin/utah/blob/main/scripts/install-packages.py) (Package resolver), [`scripts/generate-site-data.py`](https://github.com/projectbluefin/utah/blob/main/scripts/generate-site-data.py) (Data generator), [`iso/live/Containerfile`](https://github.com/projectbluefin/utah/blob/main/iso/live/Containerfile) (Live ISO recipe)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compose["Image composition"]
  node_containerfile["Image recipe"]
  node_base["Hummingbird base"]
  node_factory["Desktop OCI"]
  node_bluefin_manifest["Bluefin contract<br/>[bluefin.toml]"]
  node_utah_manifest["Utah overlay<br/>[utah.toml]"]
  node_installer["Package resolver"]
  node_contract_record["Resolved contract"]
end

subgraph group_desktop["Desktop system"]
  node_desktop_contract["Desktop policy"]
  node_system_files["System defaults"]
  node_services["Service setup"]
end

subgraph group_install["Live installation"]
  node_iso_recipe["Live ISO recipe"]
  node_iso_builder["ISO builder<br/>[build-iso.sh]"]
  node_live_config["Live configuration<br/>[configure-live.sh]"]
  node_installer_payload["Installer payload<br/>[recipe.json]"]
  node_flatpaks["Flatpak setup"]
end

subgraph group_status["Project status"]
  node_status_page["Status page<br/>[index.html]"]
  node_package_data["Package data<br/>[packages.json]"]
  node_data_generator["Data generator"]
end

node_builder(("Image builder"))
node_installed_user(("Installing user"))
node_browser(("Page visitor"))
node_github_api["GitHub API"]

node_builder -->|"builds"| node_containerfile
node_containerfile -->|"starts from"| node_base
node_containerfile -->|"consumes"| node_factory
node_containerfile -->|"runs"| node_installer
node_installer -->|"reads"| node_bluefin_manifest
node_installer -->|"reads"| node_utah_manifest
node_installer -->|"writes"| node_contract_record
node_containerfile -->|"verifies"| node_desktop_contract
node_containerfile -->|"configures"| node_services
node_services -->|"installs defaults"| node_system_files
node_builder -->|"builds media"| node_iso_builder
node_iso_builder -->|"uses"| node_iso_recipe
node_iso_recipe -->|"includes"| node_live_config
node_iso_recipe -->|"embeds"| node_installer_payload
node_live_config -->|"runs"| node_flatpaks
node_installed_user -->|"boots media"| node_iso_builder
node_browser -->|"views"| node_status_page
node_status_page -->|"renders"| node_package_data
node_data_generator -->|"reads"| node_bluefin_manifest
node_data_generator -->|"reads"| node_utah_manifest
node_data_generator -->|"generates"| node_package_data
node_status_page -.->|"fetches status"| node_github_api

click node_containerfile "https://github.com/projectbluefin/utah/blob/main/Containerfile"
click node_bluefin_manifest "https://github.com/projectbluefin/utah/blob/main/packages/bluefin.toml"
click node_utah_manifest "https://github.com/projectbluefin/utah/blob/main/packages/utah.toml"
click node_installer "https://github.com/projectbluefin/utah/blob/main/scripts/install-packages.py"
click node_desktop_contract "https://github.com/projectbluefin/utah/blob/main/contracts/bluefin-desktop.toml"
click node_system_files "https://github.com/projectbluefin/utah/tree/main/system_files/shared"
click node_services "https://github.com/projectbluefin/utah/blob/main/scripts/configure-services.sh"
click node_iso_recipe "https://github.com/projectbluefin/utah/blob/main/iso/live/Containerfile"
click node_iso_builder "https://github.com/projectbluefin/utah/blob/main/iso/scripts/build-iso.sh"
click node_live_config "https://github.com/projectbluefin/utah/blob/main/iso/live/src/configure-live.sh"
click node_installer_payload "https://github.com/projectbluefin/utah/blob/main/iso/live/src/etc/bootc-installer/recipe.json"
click node_flatpaks "https://github.com/projectbluefin/utah/blob/main/iso/live/src/install-flatpaks.sh"
click node_status_page "https://github.com/projectbluefin/utah/blob/main/site/index.html"
click node_package_data "https://github.com/projectbluefin/utah/blob/main/site/data/packages.json"
click node_data_generator "https://github.com/projectbluefin/utah/blob/main/scripts/generate-site-data.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_containerfile,node_base,node_factory,node_bluefin_manifest,node_utah_manifest,node_installer,node_contract_record,node_installed_user toneBlue
class node_desktop_contract,node_system_files,node_services toneAmber
class node_iso_recipe,node_iso_builder,node_live_config,node_installer_payload,node_flatpaks,node_github_api toneMint
class node_status_page,node_package_data,node_data_generator toneRose
class node_builder,node_browser toneIndigo
```

## Components

### Image composition

- [Image recipe](https://github.com/projectbluefin/utah/blob/main/Containerfile): `Containerfile`
- **Hummingbird base**
- **Desktop OCI**
- [Bluefin contract](https://github.com/projectbluefin/utah/blob/main/packages/bluefin.toml): `packages/bluefin.toml`
- [Utah overlay](https://github.com/projectbluefin/utah/blob/main/packages/utah.toml): `packages/utah.toml`
- [Package resolver](https://github.com/projectbluefin/utah/blob/main/scripts/install-packages.py): `scripts/install-packages.py`
- **Resolved contract**

### Desktop system

- [Desktop policy](https://github.com/projectbluefin/utah/blob/main/contracts/bluefin-desktop.toml): `contracts/bluefin-desktop.toml`
- [System defaults](https://github.com/projectbluefin/utah/tree/main/system_files/shared): `system_files/shared`
- [Service setup](https://github.com/projectbluefin/utah/blob/main/scripts/configure-services.sh): `scripts/configure-services.sh`

### Live installation

- [Live ISO recipe](https://github.com/projectbluefin/utah/blob/main/iso/live/Containerfile): `iso/live/Containerfile`
- [ISO builder](https://github.com/projectbluefin/utah/blob/main/iso/scripts/build-iso.sh): `iso/scripts/build-iso.sh`
- [Live configuration](https://github.com/projectbluefin/utah/blob/main/iso/live/src/configure-live.sh): `iso/live/src/configure-live.sh`
- [Installer payload](https://github.com/projectbluefin/utah/blob/main/iso/live/src/etc/bootc-installer/recipe.json): `iso/live/src/etc/bootc-installer/recipe.json`
- [Flatpak setup](https://github.com/projectbluefin/utah/blob/main/iso/live/src/install-flatpaks.sh): `iso/live/src/install-flatpaks.sh`

### Project status

- [Status page](https://github.com/projectbluefin/utah/blob/main/site/index.html): `site/index.html`
- [Package data](https://github.com/projectbluefin/utah/blob/main/site/data/packages.json): `site/data/packages.json`
- [Data generator](https://github.com/projectbluefin/utah/blob/main/scripts/generate-site-data.py): `scripts/generate-site-data.py`

### Other components

- **Image builder**
- **Installing user**
- **Page visitor**
- **GitHub API**

## Connections

- Image builder → Image recipe: builds
- Image recipe → Hummingbird base: starts from
- Image recipe → Desktop OCI: consumes
- Image recipe → Package resolver: runs
- Package resolver → Bluefin contract: reads
- Package resolver → Utah overlay: reads
- Package resolver → Resolved contract: writes
- Image recipe → Desktop policy: verifies
- Image recipe → Service setup: configures
- Service setup → System defaults: installs defaults
- Image builder → ISO builder: builds media
- ISO builder → Live ISO recipe: uses
- Live ISO recipe → Live configuration: includes
- Live ISO recipe → Installer payload: embeds
- Live configuration → Flatpak setup: runs
- Installing user → ISO builder: boots media
- Page visitor → Status page: views
- Status page → Package data: renders
- Data generator → Bluefin contract: reads
- Data generator → Utah overlay: reads
- Data generator → Package data: generates
- Status page → GitHub API: fetches status