# gardenlinux/gardenlinux architecture

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

- Interactive diagram: https://gitdiagram.com/gardenlinux/gardenlinux
- Repository: https://github.com/gardenlinux/gardenlinux

## Overview

##### Project type and purpose
- This is an open-source operating-system image build toolkit (“Garden Linux”) rather than a traditional web or microservice application.
- It orchestrates assembling a custom Linux root filesystem and initramfs by combining:
- A minimal “base” OS package set and dracut + kernel configuration
- A set of modular “features” (each in its own directory under features/)
- Flavor definitions (bare_flavors/ and flavors.yaml) for different target runtimes (bare‐metal containers, Python, Node.js, cloud images, etc.)
- It produces outputs such as OCI container images, cloud disk images (AWS AMIs, Azure VHDs, OpenStack QCOW2), ISO/ PXE images, and signed artifacts.

##### File structure
- Top‐level orchestration:
- Makefile, VERSION files, bin/ (shell and Python scripts to drive builds), hack/ (helper scripts), tools/
- .github/workflows/ (CI definitions for build, test, nightly, release, S3/OCI publishing)
- Core modules and inputs:
- features/ – each subdirectory is a self-contained plugin defining file.include/exclude, package lists, dracut modules, tests, and metadata (info.yaml)
- bare_flavors/ – minimal rootfs definitions per language/runtime
- flavors.yaml – maps flavor names to features & bare_flavors sets
- Build artifacts and outputs:
- build/ and build_bare_flavors/ (intermediate)
- cert/ for signing keys and configs
- images/ (Containerfiles for kmodbuild image)
- Testing:
- tests/, tests/images/, tests/platformSetup/ – PyTest suites, chroot/container harnesses, Terraform modules for platform integration tests

##### README for additional insights
- (No content provided, but typical sections would describe the build pipeline, plugin system, CI flow, and publish targets.)

a. Main components
- Developer / GitHub (source code, PRs)
- CI Orchestrator (GitHub Actions workflows)
- Build Engine (Docker/Podman on CI runners or local make)
- Core Build Orchestrator Scripts (Makefile, bin/, hack/)
- Plugin Registry (features/)
- Flavor Definitions (bare_flavors/, flavors.yaml)
- Signing Subsystem (cert/)
- Test Harness (tests/, platformSetup/)
- Artifact Store(s)
– OCI registry (publish_oci_containers.yml)
– S3 buckets (publish_s3.yml)
– AMI registries (AWS, GCP, Azure pipelines)
b. Relationships / data flows
1. Developer merges code → triggers GitHub Actions
2. CI runner checks out code → invokes build workflows:
– Lint / shellcheck / static checks
– Build bare_flavors (docker build of minimal images)
– Combine bare_flavors + features → Containerfile dracut build → produce rootfs + initramfs
– Package and sign with cert/
3. Run tests in containers or chroots (tests/platformSetup or Terraform)
4. Publish artifacts to external stores (OCI registry, S3, AMI catalogs)
c. Architectural patterns / principles
- Modular plugin architecture: each feature encapsulates its files, config, and tests.
- Convention-over-configuration: features follow a uniform layout; flavors.yaml drives composition.
- CI-driven reproducibility: workflows define matrix builds for each flavor/platform.
- Separation of concerns:
– Orchestrator scripts (bin/, hack/) vs. plugin code (features/) vs. test code (tests/)
d. Key technologies / frameworks
- Docker/Podman + Containerfile-based builds
- dracut for generating initramfs
- GitHub Actions for CI/CD
- Bash, Python (bin/*.py, tests in pytest)
- Terraform modules (tests/platformSetup/tofu) for integration tests

##### Elements
- **Clear labels** for each component (e.g., “Feature Plugin”, “Flavor Definition”, “CI Runner”, “OCI Registry”).
– Trigger flow (Dev → GitHub Actions → Build Engine)
– Data flow (features + flavors → rootfs image → signed artifact → external store)
– Test invocation flows (test harness → container or chroot)
– Green for CI/CD pipelines (GitHub Actions workflows)
– Yellow for external services (Docker Engine, S3, OCI Registry, Cloud APIs)
– Gray for artifacts (images/, build/)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer["Developer"]:::external
    Developer -->|"merge code"| CI["GitHub Actions\n(CI Orchestrator)"]:::ci
    CI -->|"run workflows"| BE["Build Engine / Orchestrator Scripts"]:::ci

    subgraph "Internal Code Modules"
        MF["Makefile, bin/, hack/"]:::code
        PR["Plugin Registry\n(features/)"]:::code
        FD["Flavor Definitions\n(bare_flavors/, flavors.yaml)"]:::code
        SS["Signing Subsystem\n(cert/)"]:::code
        TL["Auxiliary Tools\n(tools/)"]:::code
        DM["Versioning & Metadata\n(VERSION, VERSION.md)"]:::code
        DOC["Documentation\n(docs/)"]:::code
    end
    BE -->|"reads"| MF
    BE -->|"reads"| PR
    BE -->|"reads"| FD
    BE -->|"reads"| TL

    subgraph "Build Process"
        IB["Intermediate Artifacts\n(build/, build_bare_flavors/)"]:::artifact
        IMG["Container Build Image\n(kmodbuild Containerfile)"]:::artifact
        BE -->|"produce"| IB
        BE -->|"uses"| IMG
        BE -->|"signs"| SS
    end

    subgraph "Test Harness"
        T1["Tests\n(tests/)"]:::code
        T2["Platform Setup\n(tests/platformSetup/)"]:::code
        T3["Image Tests\n(tests/images/)"]:::code
    end
    SS -->|"provide artifacts to"| T1
    SS -->|"provide artifacts to"| T2
    SS -->|"provide artifacts to"| T3

    subgraph "Publication Workflows"
        POCI["publish_oci_containers.yml"]:::ci
        PS3["publish_s3.yml"]:::ci
    end
    T1 -->|"on success"| POCI
    T2 -->|"on success"| PS3
    T3 -->|"on success"| POCI

    subgraph "External Services"
        DKR["Docker Engine"]:::external
        OCI["OCI Registry"]:::external
        S3["S3 Bucket"]:::external
        CLOUD["Cloud APIs\n(AWS, GCP, Azure)"]:::external
    end
    BE -->|"opens container build"| DKR
    POCI -->|"push images"| OCI
    PS3 -->|"upload artifacts"| S3
    POCI -->|"register AMI"| CLOUD

    %% Click Events
    click CI "https://github.com/gardenlinux/gardenlinux/tree/main/.github/workflows/"
    click MF "https://github.com/gardenlinux/gardenlinux/tree/main/Makefile"
    click MF "https://github.com/gardenlinux/gardenlinux/tree/main/bin/"
    click MF "https://github.com/gardenlinux/gardenlinux/tree/main/hack/"
    click PR "https://github.com/gardenlinux/gardenlinux/tree/main/features/"
    click FD "https://github.com/gardenlinux/gardenlinux/tree/main/bare_flavors/"
    click FD "https://github.com/gardenlinux/gardenlinux/blob/main/flavors.yaml"
    click SS "https://github.com/gardenlinux/gardenlinux/tree/main/cert/"
    click TL "https://github.com/gardenlinux/gardenlinux/tree/main/tools/"
    click DM "https://github.com/gardenlinux/gardenlinux/tree/main/VERSION"
    click DM "https://github.com/gardenlinux/gardenlinux/blob/main/VERSION.md"
    click DOC "https://github.com/gardenlinux/gardenlinux/tree/main/docs/"
    click IB "https://github.com/gardenlinux/gardenlinux/tree/main/build/"
    click IB "https://github.com/gardenlinux/gardenlinux/tree/main/build_bare_flavors/"
    click IMG "https://github.com/gardenlinux/gardenlinux/tree/main/images/kmodbuild/Containerfile"
    click T1 "https://github.com/gardenlinux/gardenlinux/tree/main/tests/"
    click T2 "https://github.com/gardenlinux/gardenlinux/tree/main/tests/platformSetup/"
    click T3 "https://github.com/gardenlinux/gardenlinux/tree/main/tests/images/"
    click POCI "https://github.com/gardenlinux/gardenlinux/blob/main/.github/workflows/publish_oci_containers.yml"
    click PS3 "https://github.com/gardenlinux/gardenlinux/blob/main/.github/workflows/publish_s3.yml"

    %% Styles
    classDef code fill:#cce5ff,stroke:#004085,color:#004085
    classDef ci fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
    classDef artifact fill:#e2e3e5,stroke:#383d41,color:#383d41
```
