# kairos-io/hadron architecture

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

- Interactive diagram: https://gitdiagram.com/kairos-io/hadron
- Repository: https://github.com/kairos-io/hadron

## Overview

##### Project type and purpose
- Hadron Linux is a minimal, foundational Linux distribution builder and image pipeline tailored for cloud and edge deployments.
- It assembles upstream-vanilla components (musl libc, systemd, Linux kernels), applies minimal patches, and outputs container images, ISOs, and VM-runnable artifacts.
- The Makefile, Dockerfile, and updatecli.d folder orchestrate build, update, and release processes; tests verify boot and upgrade functionality; docs describe architecture and usage.

##### File structure
- Top-level orchestrators:
- Makefile & Dockerfile – define build targets (build image, devel-iso, run-qemu, build-kairos, pull-image, etc.).
- updatecli.d – YAML recipes for automated dependency updates (kernel versions, tools, libraries).
- .github/workflows – CI pipelines for multi-arch builds, autobumping, example validation, docs deployment.
- Source inputs:
- files/ – configuration snippets, service unit files, shell profiles, patches to upstream components.
- patches/ – custom patch files applied to musl or other sources.
- examples/ – sample Dockerfiles illustrating how to extend or use Hadron.
- Documentation site:
- docs/ – Hugo site (config.toml, layouts, static assets) for online documentation, including architecture explanations.
- Tests:
- tests/ – Go test suite for acceptance tests (booting, secure-boot, FIPS, custom partitioning), assets for VM images and UEFI variables.

##### README for additional insights
- The architecture section describes core components (musl, systemd, kernel), boot methods (USI/UKI vs. GRUB), upgrade system (A/B atomic via Kairos agent).
- Development section reveals Make targets and build arguments (BOOTLOADER, KERNEL_TYPE, KUBERNETES_DISTRO/​VERSION, ARCH, FIPS).

##### Final remarks
- Essential elements: inputs, orchestration logic, execution environment, outputs, testing, and CI/CD.
- Don’t over-engineer; separate the project into logical layers and components.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Inputs
    subgraph "Input Sources"
        direction TB
        UpstreamRepos["Upstream Repositories\n(musl, kernel, systemd)"]:::external
        Files["files/"]:::external
        Patches["patches/"]:::external
        Examples["examples/"]:::external
    end

    %% Build Orchestrator
    subgraph "Build Orchestrator"
        direction TB
        Makefile["Makefile"]:::orchestration
        Dockerfile["Dockerfile"]:::orchestration
        Updatecli["updatecli.d/"]:::orchestration
    end

    %% Build Environment
    BuildEnv["Docker Build Env & QEMU"]:::orchestration

    %% Image Builder
    ImageBuilder["Image Builder\n(Hadron base & Kairos)"]:::orchestration

    %% Artifact Outputs
    Artifacts["Artifact Outputs\n(images, ISOs, VM"]:::output

    %% Testing Framework
    Testing["Testing Framework\n(Go tests & QEMU boots)"]:::output

    %% CI/CD Pipeline
    CI["CI/CD\nGitHub Actions"]:::ci

    %% Documentation Site
    Docs["Documentation Site\n(Hugo)"]:::ci

    %% Connections
    UpstreamRepos --> Makefile
    Files --> Makefile
    Patches --> Makefile
    Examples --> Makefile

    Makefile --> Dockerfile
    Makefile --> Updatecli
    Makefile --> BuildEnv
    Dockerfile --> BuildEnv
    Updatecli --> CI

    BuildEnv --> ImageBuilder
    ImageBuilder --> Artifacts
    Artifacts --> Testing

    CI --> Makefile
    CI --> Docs
    CI --> Testing

    %% Click Events
    click Files "https://github.com/kairos-io/hadron/tree/main/files/"
    click Patches "https://github.com/kairos-io/hadron/tree/main/patches/"
    click Examples "https://github.com/kairos-io/hadron/tree/main/examples/"
    click Makefile "https://github.com/kairos-io/hadron/tree/main/Makefile"
    click Dockerfile "https://github.com/kairos-io/hadron/tree/main/Dockerfile"
    click Updatecli "https://github.com/kairos-io/hadron/tree/main/updatecli.d/"
    click CI "https://github.com/kairos-io/hadron/tree/main/.github/workflows/"
    click Docs "https://github.com/kairos-io/hadron/tree/main/docs/"
    click Testing "https://github.com/kairos-io/hadron/tree/main/tests/"

    %% Styles
    classDef external fill:#c8e6c9,stroke:#388e3c,color:#000
    classDef orchestration fill:#bbdefb,stroke:#1976d2,color:#000
    classDef output fill:#ffe0b2,stroke:#f57c00,color:#000
    classDef ci fill:#e1bee7,stroke:#8e24aa,color:#000
```
