# dozlab/rootfs-manager architecture

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

- Interactive diagram: https://gitdiagram.com/dozlab/rootfs-manager
- Repository: https://github.com/dozlab/rootfs-manager

## Overview

##### Project type and purpose
- This repository (“rootfs-manager”) is a CLI/toolkit for building and managing custom root filesystems (rootfs) and initramfs images using Docker and Makefiles. It includes:
- base_image: a minimal container image builder
- init-setup: a customizable initramfs/init script builder
- labs: three hands-on examples (custom initrd, Kubernetes lab, VM lab)
- Its primary use cases are:
- Automating rootfs/initrd creation
- Demonstrating how to plug those images into a VM, Kubernetes cluster, or bare-metal-like environment

##### File structure
- Top-level:
- .github/workflows: GitHub Actions pipelines (base image build, custom-initrd, init-setup, k8, vm)
- base_image/, init-setup/: two core modules, each with Dockerfile + Makefile
- labs/: three independent demo projects, each with its own Dockerfile/Makefile (and Go code in custom-initrd)
- README.md: minimal high-level description
- Patterns:
- Each module is containerized via a Dockerfile
- Makefiles orchestrate builds and local testing
- CI workflows mirror local make targets to produce published images or test labs

##### README for additional insights
- The README only gives the name—but its directory layout and init-setup/README.md contain the meat of the architecture:
- init-setup/README.md describes how to assemble a custom initramfs via init.sh
- Workflow YAMLs show the target environments (VM, Kubernetes, custom-return, etc.)

a. Main components:
- Developer workstation: runs Makefile targets
- Docker Engine: builds container images
- Modules:
- Base Image Builder
- Init-Setup Builder
- Lab Environments (Custom-initrd, K8_lab, VM_lab)
- GitHub Actions CI: automated pipelines
- Container Registry / Artifact Store
- Target Runtimes: VM Hypervisor, Kubernetes Cluster, Bootloader/initrd loader
b. Relationships & interactions:
- Developer → (git push) → GitHub Actions
- GitHub Actions → Docker Engine → builds module images → pushes to registry
- Developer (locally) → Makefile → Docker Engine → builds & runs containers
- Base image output → consumed by init-setup and labs
- Init-setup image + configuration → custom initramfs → used by VM and bootloader
c. Important patterns & principles:
- Modular containerization: each subproject is isolated in its own Dockerfile
- CI-as-infrastructure: GitHub Actions replicate local Makefile logic
- Layered building: base_image → init-setup → labs
d. Technologies & frameworks:
- Docker & Dockerfiles
- Make (Makefile orchestration)
- GitHub Actions (YAML workflows)
- Go (in labs/custom-initrd for init binary)
- K8s manifests (implicitly in labs/k8_lab)
- Shell scripts (init.sh, local_create_image.sh)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure
    Developer["Developer Workstation"]:::infra
    GitHubActions["GitHub Actions CI"]:::infra
    DockerEngine["Docker Engine"]:::infra
    Registry["Container Registry"]:::infra

    %% Modules
    subgraph "Modules" 
        BaseImage["Base Image Builder"]:::module
        InitSetup["Init-Setup Builder"]:::module
    end

    %% Labs
    subgraph "Labs"
        CustomInitrd["Custom Initrd Lab"]:::module
        K8Lab["Kubernetes Lab"]:::module
        VMLab["VM Lab"]:::module
    end

    %% Runtimes
    Bootloader["Bootloader / initrd Loader"]:::runtime
    K8sCluster["Kubernetes Cluster"]:::runtime
    VMHypervisor["VM Hypervisor"]:::runtime

    %% Flows
    Developer -->|"git push"| GitHubActions
    Developer -->|"make / docker build"| DockerEngine
    GitHubActions -->|"runs workflows"| DockerEngine
    DockerEngine -->|"push images"| Registry

    Registry -->|"pull base image"| BaseImage
    Registry -->|"pull image"| InitSetup
    Registry -->|"pull image"| CustomInitrd
    Registry -->|"pull image"| K8Lab
    Registry -->|"pull image"| VMLab

    BaseImage -->|"artifact"| InitSetup
    BaseImage -->|"artifact"| CustomInitrd
    BaseImage -->|"artifact"| K8Lab
    BaseImage -->|"artifact"| VMLab

    InitSetup -->|"build initramfs"| CustomInitrd
    InitSetup -->|"build initramfs"| VMLab

    CustomInitrd -->|"run"| Bootloader
    VMLab -->|"run"| VMHypervisor
    K8Lab -->|"deploy"| K8sCluster

    %% Click Events
    click BaseImage "https://github.com/dozlab/rootfs-manager/tree/main/base_image/"
    click InitSetup "https://github.com/dozlab/rootfs-manager/tree/main/init-setup/"
    click CustomInitrd "https://github.com/dozlab/rootfs-manager/tree/main/labs/custom-initrd/"
    click K8Lab "https://github.com/dozlab/rootfs-manager/tree/main/labs/k8_lab/"
    click VMLab "https://github.com/dozlab/rootfs-manager/tree/main/labs/vm_lab/"
    click GitHubActions "https://github.com/dozlab/rootfs-manager/tree/main/.github/workflows/"

    %% Styles
    classDef infra fill:#daf5d4,stroke:#2d6a4f,color:#1b4332;
    classDef module fill:#e0f7fa,stroke:#006064,color:#004d40;
    classDef runtime fill:#ffe5b4,stroke:#e65100,color:#bf360c;
```
