# stratos-linux/gnome-iso architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source ISO-builder tool for Arch-based distributions (“StratOS iso”).
- Its purpose is to assemble a bootable ISO containing a customized Arch Linux system, including theming, default configs, and installer integration.

##### File structure
- Top-level
- .github/workflows/deploy.yml → CI pipeline that invokes the build
- .gitmodules → external submodules (e.g., installer configs)
- README.md, LICENSE
- airootfs/ (the overlay root filesystem)
- etc/  → system defaults (grub, pacman, networkd, systemd services, dconf profiles, user skeletons)
- root/ → root-user defaults (automation scripts, SSH keys)
- usr/
– lib/systemd/system → custom service units
– local/share/livecd-sound → sound config
- (Implicit) build.sh or similar script at repo root that drives archiso

##### README for additional insights
- Uses Arch’s official `archiso` package to assemble the ISO
- Build process: clone + `./build.sh` → ISO for VM or bare metal

##### Main components & interactions
a. Components
1. GitHub Repository
– Source of build scripts, airootfs overlay, submodules
2. CI/CD Runner (GitHub Actions)
– Executes deploy.yml → checks out code, calls build.sh
3. Host Environment
– Must have `archiso` installed
– Runs `build.sh` either locally or within CI
4. archiso Toolchain
– Stage 1 (bootstrap) & Stage 2 (chroot + overlay)
– Consumes airootfs/ directory and `pacman.conf`, `mkinitcpio.conf`, hooks
5. airootfs Overlay
– Merges `etc/`, `usr/`, and `root/` on top of a base Arch filesystem
6. Git Submodules
– Additional configs (e.g., Calamares installer, kernel hooks)
7. Output ISO Artifact
– Bootable ISO image, packaged with GRUB, systemd, theming, installer
8. Target Environment
– VM or bare-metal installer consuming the ISO

b. Data flows / relationships
- Developer pushes code → GitHub Repo
- Push event triggers CI/CD Runner → checks out code + submodules
- CI/CD or local Host Env launches archiso via build.sh
→ archiso builds in two stages:
- Stage 1: bootstrap minimal base
- Stage 2: chroot + overlay using airootfs
- Applies pacman hooks, mkinitcpio, custom systemd units, themes
- archiso outputs final ISO → stored as CI artifact or local file
- ISO is downloaded/deployed to VM/bare metal

c. Architectural patterns & design principles
- Overlay pattern: airootfs acts as a drop-in overlay onto Arch base
- Infrastructure-as-code: all system configs live in Git, reproducible build
- Micro-phases: separate bootstrap vs. chroot phases in archiso

d. Key technologies/frameworks
- archiso (Bash, rsync, mkarchiso)
- pacman (package manager config & hooks)
- mkinitcpio (initramfs generators)
- systemd (service unit overlays)
- dconf (desktop settings)
- GRUB (bootloader theming)
- GitHub Actions (CI/CD)
- Git submodules (external config bundles)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Pipeline components
    subgraph "Source & CI Pipeline"
        direction TB
        Repo["GitHub Repository"]:::pipeline
        Submodules["Git Submodules"]:::pipeline
        CI["CI/CD Runner"]:::pipeline
    end

    %% Host environment
    Host["Host Environment"]:::pipeline

    %% Build tools
    subgraph "Build Tools"
        direction TB
        BuildScript["build.sh"]:::build
        Stage1["archiso Stage 1\n(bootstrap base)"]:::build
        Stage2["archiso Stage 2\n(chroot + overlay)"]:::build
    end

    %% Overlay configurations
    subgraph "airootfs Overlay" 
        direction TB
        Overlay["airootfs/"]:::overlay
        SystemDefaults["System Defaults\n(/etc/)"]:::overlay
        RootDefaults["Root-user Defaults"]:::overlay
        PacmanHooks["pacman Hooks & Config"]:::overlay
        MkinitcpioCfg["mkinitcpio Config & Presets"]:::overlay
        SystemdUnits["systemd Service Overlays"]:::overlay
        Theming["Theming Assets"]:::overlay
        Installer["Installer Integration\n(Calamares)"]:::overlay
    end

    %% Output artifact
    ISO["Output ISO Artifact"]:::artifact

    %% Target environment
    Target["VM / Bare-metal Target"]:::artifact

    %% Connections
    Repo -->|push triggers| CI
    Repo -->|defines| Submodules
    CI -->|checks out code| Host
    Host -->|runs| BuildScript
    BuildScript -->|invokes| Stage1
    Stage1 -->|produces base fs| Stage2
    Stage2 -->|applies overlay| Overlay
    Overlay --> SystemDefaults
    Overlay --> RootDefaults
    Overlay --> PacmanHooks
    Overlay --> MkinitcpioCfg
    Overlay --> SystemdUnits
    Overlay --> Theming
    Overlay --> Installer
    Stage2 -->|creates| ISO
    ISO -->|deployed to| Target

    %% Click Events
    click Repo "https://github.com/stratos-linux/gnome-iso/blob/main//.gitmodules"
    click CI "https://github.com/stratos-linux/gnome-iso/blob/main//.github/workflows/deploy.yml"
    click Submodules "https://github.com/stratos-linux/gnome-iso/blob/main//.gitmodules"
    click Overlay "https://github.com/stratos-linux/gnome-iso/tree/main//airootfs/"
    click SystemDefaults "https://github.com/stratos-linux/gnome-iso/tree/main//airootfs/etc/"
    click RootDefaults "https://github.com/stratos-linux/gnome-iso/blob/main//airootfs/root/.automated_script.sh"
    click PacmanHooks "https://github.com/stratos-linux/gnome-iso/tree/main//airootfs/etc/pacman.d/hooks/"
    click MkinitcpioCfg "https://github.com/stratos-linux/gnome-iso/blob/main//airootfs/etc/mkinitcpio.conf"
    click SystemdUnits "https://github.com/stratos-linux/gnome-iso/tree/main//airootfs/etc/systemd/system/"
    click Theming "https://github.com/stratos-linux/gnome-iso/tree/main//airootfs/usr/share/icons/"
    click Installer "https://github.com/stratos-linux/gnome-iso/blob/main//airootfs/etc/systemd/system/multi-user.target.wants/Calamares.service"

    %% Styles
    classDef pipeline fill:#FFA500,stroke:#333,stroke-width:1px
    classDef build fill:#90EE90,stroke:#333,stroke-width:1px
    classDef overlay fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef artifact fill:#DDA0DD,stroke:#333,stroke-width:1px
```
