# terracotta-linux/terracotta-iso architecture

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

- Interactive diagram: https://gitdiagram.com/terracotta-linux/terracotta-iso
- Repository: https://github.com/terracotta-linux/terracotta-iso

## Overview

Terracotta ISO assembles prebuilt Terracotta releases and an Arch Linux base into a UEFI bootable live/install image. The main path is package fetching, local repository creation, profile-based image assembly, then live boot and installer handoff. The README documents update-triggered releases and boot networking; source excerpts were unavailable, so links reflect documented relationships only.

Main entry points: [`build.sh`](https://github.com/terracotta-linux/terracotta-iso/blob/main/build.sh) (Build entrypoint), [`profile`](https://github.com/terracotta-linux/terracotta-iso/tree/main/profile) (Archiso profile), [`.github/workflows/daily-update-check.yml`](https://github.com/terracotta-linux/terracotta-iso/blob/main/.github/workflows/daily-update-check.yml) (Update check), [`fetch-packages.sh`](https://github.com/terracotta-linux/terracotta-iso/blob/main/fetch-packages.sh) (Package fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assembly["ISO assembly"]
  node_build["Build entrypoint<br/>[build.sh]"]
  node_fetch["Package fetcher<br/>[fetch-packages.sh]"]
  node_localrepo[("Local pacman repo")]
  node_mkarchiso["Image assembler"]
  node_iso["Bootable ISO"]
end

subgraph group_profile["Boot profile"]
  node_profile["Archiso profile"]
  node_packages["Package selection<br/>[packages.x86_64]"]
  node_pacman["Pacman config<br/>[pacman.conf]"]
  node_profiledef["Profile definition<br/>[profiledef.sh]"]
  node_rootfs["Live root config"]
  node_bootloader["UEFI GRUB config<br/>[grub.cfg]"]
end

subgraph group_live["Live experience"]
  node_liveboot["Live boot"]
  node_network["Network setup"]
  node_nmtui["Network UI<br/>[packages.x86_64]"]
  node_installer["Terracotta installer"]
end

subgraph group_release["Release automation"]
  node_daily["Update check"]
  node_important["Important packages"]
  node_releaseflow["Release workflow<br/>[release-iso.yml]"]
end

node_maintainer(("Maintainer"))
node_upstream["Terracotta releases"]
node_github["GitHub releases"]

node_maintainer -->|"runs"| node_build
node_build -->|"invokes"| node_fetch
node_fetch -->|"downloads packages"| node_upstream
node_fetch -->|"builds repository"| node_localrepo
node_build -->|"invokes"| node_mkarchiso
node_build -->|"passes profile"| node_profile
node_build -->|"passes config"| node_pacman
node_mkarchiso -->|"installs packages"| node_localrepo
node_mkarchiso -->|"reads"| node_profile
node_mkarchiso -->|"produces"| node_iso
node_profile -->|"defines packages"| node_packages
node_profile -->|"defines profile"| node_profiledef
node_profile -->|"includes root config"| node_rootfs
node_profile -->|"includes boot config"| node_bootloader
node_iso -->|"boots"| node_liveboot
node_liveboot -->|"starts networking"| node_network
node_liveboot -->|"hands off"| node_installer
node_network -->|"offers if disconnected"| node_nmtui
node_daily -->|"checks versions"| node_important
node_daily -->|"checks releases"| node_upstream
node_daily -->|"triggers when updated"| node_releaseflow
node_releaseflow -->|"builds ISO"| node_build
node_releaseflow -->|"publishes release"| node_github

click node_build "https://github.com/terracotta-linux/terracotta-iso/blob/main/build.sh"
click node_fetch "https://github.com/terracotta-linux/terracotta-iso/blob/main/fetch-packages.sh"
click node_profile "https://github.com/terracotta-linux/terracotta-iso/tree/main/profile"
click node_packages "https://github.com/terracotta-linux/terracotta-iso/blob/main/profile/packages.x86_64"
click node_pacman "https://github.com/terracotta-linux/terracotta-iso/blob/main/profile/pacman.conf"
click node_profiledef "https://github.com/terracotta-linux/terracotta-iso/blob/main/profile/profiledef.sh"
click node_rootfs "https://github.com/terracotta-linux/terracotta-iso/tree/main/profile/airootfs"
click node_bootloader "https://github.com/terracotta-linux/terracotta-iso/blob/main/profile/grub/grub.cfg"
click node_liveboot "https://github.com/terracotta-linux/terracotta-iso/tree/main/profile"
click node_network "https://github.com/terracotta-linux/terracotta-iso/tree/main/profile/airootfs/etc/systemd"
click node_nmtui "https://github.com/terracotta-linux/terracotta-iso/blob/main/profile/packages.x86_64"
click node_daily "https://github.com/terracotta-linux/terracotta-iso/blob/main/.github/workflows/daily-update-check.yml"
click node_important "https://github.com/terracotta-linux/terracotta-iso/blob/main/.github/important-packages.json"
click node_releaseflow "https://github.com/terracotta-linux/terracotta-iso/blob/main/.github/workflows/release-iso.yml"

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_build,node_fetch,node_localrepo,node_mkarchiso,node_iso toneBlue
class node_profile,node_packages,node_pacman,node_profiledef,node_rootfs,node_bootloader toneAmber
class node_liveboot,node_network,node_nmtui,node_installer toneMint
class node_daily,node_important,node_releaseflow toneRose
class node_maintainer,node_upstream,node_github toneIndigo
```

## Components

### ISO assembly

- [Build entrypoint](https://github.com/terracotta-linux/terracotta-iso/blob/main/build.sh): `build.sh`
- [Package fetcher](https://github.com/terracotta-linux/terracotta-iso/blob/main/fetch-packages.sh): `fetch-packages.sh`
- **Local pacman repo**
- **Image assembler**
- **Bootable ISO**

### Boot profile

- [Archiso profile](https://github.com/terracotta-linux/terracotta-iso/tree/main/profile): `profile`
- [Package selection](https://github.com/terracotta-linux/terracotta-iso/blob/main/profile/packages.x86_64): `profile/packages.x86_64`
- [Pacman config](https://github.com/terracotta-linux/terracotta-iso/blob/main/profile/pacman.conf): `profile/pacman.conf`
- [Profile definition](https://github.com/terracotta-linux/terracotta-iso/blob/main/profile/profiledef.sh): `profile/profiledef.sh`
- [Live root config](https://github.com/terracotta-linux/terracotta-iso/tree/main/profile/airootfs): `profile/airootfs`
- [UEFI GRUB config](https://github.com/terracotta-linux/terracotta-iso/blob/main/profile/grub/grub.cfg): `profile/grub/grub.cfg`

### Live experience

- [Live boot](https://github.com/terracotta-linux/terracotta-iso/tree/main/profile): `profile`
- [Network setup](https://github.com/terracotta-linux/terracotta-iso/tree/main/profile/airootfs/etc/systemd): `profile/airootfs/etc/systemd`
- [Network UI](https://github.com/terracotta-linux/terracotta-iso/blob/main/profile/packages.x86_64): `profile/packages.x86_64`
- **Terracotta installer**

### Release automation

- [Update check](https://github.com/terracotta-linux/terracotta-iso/blob/main/.github/workflows/daily-update-check.yml): `.github/workflows/daily-update-check.yml`
- [Important packages](https://github.com/terracotta-linux/terracotta-iso/blob/main/.github/important-packages.json): `.github/important-packages.json`
- [Release workflow](https://github.com/terracotta-linux/terracotta-iso/blob/main/.github/workflows/release-iso.yml): `.github/workflows/release-iso.yml`

### Other components

- **Maintainer**
- **Terracotta releases**
- **GitHub releases**

## Connections

- Maintainer → Build entrypoint: runs
- Build entrypoint → Package fetcher: invokes
- Package fetcher → Terracotta releases: downloads packages
- Package fetcher → Local pacman repo: builds repository
- Build entrypoint → Image assembler: invokes
- Build entrypoint → Archiso profile: passes profile
- Build entrypoint → Pacman config: passes config
- Image assembler → Local pacman repo: installs packages
- Image assembler → Archiso profile: reads
- Image assembler → Bootable ISO: produces
- Archiso profile → Package selection: defines packages
- Archiso profile → Profile definition: defines profile
- Archiso profile → Live root config: includes root config
- Archiso profile → UEFI GRUB config: includes boot config
- Bootable ISO → Live boot: boots
- Live boot → Network setup: starts networking
- Live boot → Terracotta installer: hands off
- Network setup → Network UI: offers if disconnected
- Update check → Important packages: checks versions
- Update check → Terracotta releases: checks releases
- Update check → Release workflow: triggers when updated
- Release workflow → Build entrypoint: builds ISO
- Release workflow → GitHub releases: publishes release