# wolfi-dev/os architecture

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

- Interactive diagram: https://gitdiagram.com/wolfi-dev/os
- Repository: https://github.com/wolfi-dev/os

## Overview

##### Project Type and Purpose
- This is an open-source, monorepo of YAML-based package manifests and CI pipelines that drive the Wolfi GNU/Linux distribution.
- Developers contribute “<package>.yaml” files and patches under each package folder; CI then builds minimal container images (via apko) and APK packages (via melange).

##### High-Level System Components
- **GitHub Repository**
- Contains all package definitions (`*.yaml`), patch directories, docs, scripts, pipeline definitions.
- Hosts `.github/workflows` for CI and `.github/chainguard` for policy-driven automation.
- **CI/CD Orchestration**
- **GitHub Actions**: triggers on push/PR, runs lint, tests, security scans.
- **Chainguard STS Workflows** (`ci-*.sts.yaml`): perform CVE scanning, SBOM generation, license checks, automated approvals.
- **Build Engines**
- **Melange**: consumes package YAML + patches → produces APK packages/artifacts.
- **Apko**: builds OCI-compatible container images (wolfi-base, wolfi-bootstrap, etc.) from package artifacts.
- **Artifact Stores**
- **Wolfi Package Repository**: an HTTP-served APK index at `packages.wolfi.dev/os`.
- **Container Registry**: Chainguard’s OCI registry (`cgr.dev/chainguard/wolfi-base`).
- **Public Signing Keys**: served alongside the repository.
- **Local Development**
- `.devcontainer` and `.vscode` configurations for standardized IDE experience.
- `Makefile` and top-level scripts drive local testing, linting, packaging.

##### Relationships & Data Flows
- Developer commits YAML → GitHub repo
→ GitHub Actions + Chainguard CI run validations (lint, tests, security scans)
→ On approval, Melange builds APKs → Push to Wolfi package index
→ Apko builds images from index → Push to OCI registry
- Downstream systems (users, Kubernetes clusters, CI for container images) pull from the package index or OCI registry.

##### Architectural Patterns & Principles
- **Mono-repo** organizing thousands of small package definitions.
- **GitOps/Policy as Code**: workflows and policies drive quality and security gating.
- **Pipeline as Code**: pipelines defined alongside code in `pipelines/` and `.github/`.
- **Separation of Concerns**:
- Package metadata (YAML) vs. build logic (melange/apko) vs. CI policy (sts.yaml).

##### Technologies & Frameworks
- **GitHub Actions**, **Chainguard STS** for CI/CD
- **Melange** (Go-based APK builder)
- **Apko** (Go-based OCI image builder)
- **Docker/OCI Registry** (`cgr.dev`), HTTP server for APK repo
- **YAML** manifest format, Make, shell scripts for orchestration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Code and Repo
    subgraph "Source Code & Repo" 
        direction TB
        Dev["Developer"]:::developer
        Repo["GitHub Repository"]:::repo
        Dev -->|"commit YAML & patches"| Repo

        subgraph "Repository Structure"
            direction TB
            Manifests["Package Manifests (*.yaml)"]:::repo
            Patches["Patch Directories"]:::repo
            Workflows["GitHub Actions Workflows"]:::ci
            STS["Chainguard STS Workflows"]:::ci
            Pipelines["Pipelines as Code (pipelines/)"]:::repo
            DevConfig["Local Dev Config (.devcontainer, .vscode)"]:::tools
            Scripts["Scripts & Makefile"]:::tools
            Keys["Artifact Signing Keys"]:::repo
            Docs["Documentation (docs/)"]:::docs
        end

        Repo --> Manifests
        Repo --> Patches
        Repo --> Workflows
        Repo --> STS
        Repo --> Pipelines
        Repo --> DevConfig
        Repo --> Scripts
        Repo --> Keys
        Repo --> Docs
    end

    %% CI/CD
    subgraph "CI/CD Orchestration"
        direction TB
        Actions["GitHub Actions"]:::ci
        STS
        Actions -->|"lint/tests/security scans"| STS
    end

    Repo -->|"trigger CI on push/PR"| Actions

    %% Build Engines
    subgraph "Build Tools"
        direction TB
        Melange["Melange (APK Builder)"]:::build
        Apko["Apko (OCI Image Builder)"]:::build
    end

    STS -->|"on approval build APKs"| Melange
    Melange -->|"APK artifacts/index"| PackageRepo
    PackageRepo["Wolfi Package Repository\n(packages.wolfi.dev/os)"]:::store
    PackageRepo -->|"serve APK index"| Apko
    Apko -->|"OCI images"| ContainerReg
    ContainerReg["Container Registry\n(cgr.dev/chainguard)"]:::store

    %% Artifact Stores and Consumers
    subgraph "Stores & Consumers"
        direction TB
        PackageRepo
        ContainerReg
        KeysServing["Public Signing Keys"]:::store
        Users["Downstream Consumers\n(users, k8s clusters)"]:::consumer
    end

    Keys --> KeysServing
    PackageRepo --> Users
    ContainerReg --> Users

    %% Click Events
    click Workflows "https://github.com/wolfi-dev/os/tree/main/.github/workflows/"
    click STS "https://github.com/wolfi-dev/os/blob/main/.github/chainguard/*.sts.yaml"
    click Manifests "https://github.com/wolfi-dev/os/blob/main/./*.yaml"
    click Melange "https://github.com/wolfi-dev/os/blob/main/melange.yaml"
    click Melange "https://github.com/wolfi-dev/os/tree/main/melange/"
    click Apko "https://github.com/wolfi-dev/os/blob/main/apko.yaml"
    click Keys "https://github.com/wolfi-dev/os/blob/main/wolfi-keys.yaml"
    click Keys "https://github.com/wolfi-dev/os/tree/main/wolfi-keys/"
    click Pipelines "https://github.com/wolfi-dev/os/tree/main/pipelines/"
    click DevConfig "https://github.com/wolfi-dev/os/blob/main/.devcontainer/devcontainer.json"
    click DevConfig "https://github.com/wolfi-dev/os/tree/main/.vscode/"
    click Scripts "https://github.com/wolfi-dev/os/tree/main/Makefile"
    click Scripts "https://github.com/wolfi-dev/os/tree/main/scripts/"
    click Docs "https://github.com/wolfi-dev/os/tree/main/docs/"

    %% Styles
    classDef developer fill:#AEDFF7,stroke:#3399FF,color:#000
    classDef repo fill:#D0E4FE,stroke:#3366CC,color:#000
    classDef ci fill:#FFD8A8,stroke:#FF9900,color:#000
    classDef build fill:#C8FACC,stroke:#33CC33,color:#000
    classDef store fill:#E3D4FC,stroke:#6633CC,color:#000
    classDef consumer fill:#F2F2F2,stroke:#999999,color:#000
    classDef tools fill:#F0F0F0,stroke:#CCCCCC,color:#000
    classDef docs fill:#FFF4CC,stroke:#CC9900,color:#000
```
