# rtvkiz/minimal architecture

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

- Interactive diagram: https://gitdiagram.com/rtvkiz/minimal
- Repository: https://github.com/rtvkiz/minimal

## Overview

#### Purpose and entry points
This repository defines and publishes 96 small, hardened OCI container images for `linux/amd64` and `linux/arm64`. Primary developer entry points are root Make targets (`Makefile`), per-image build recipes, and GitHub Actions. Published artifacts are consumed from GHCR; the public catalog is built as a static site.
Paths: `Makefile`, `README.md`, `.github/workflows/build.yml`

#### Image recipe model
Each image is an isolated top-level component directory. Production and development image definitions use apko YAML; source-built applications add a melange package recipe. This separates package construction from final image assembly, while allowing apko-only images where no custom package build is required.
Paths: `caddy/melange.yaml`, `caddy/apko/caddy.yaml`, `caddy/apko/caddy-dev.yaml`

#### Catalog as the registry boundary
`catalog.json` is the canonical declared image inventory and is validated against CI’s build matrix. It is also an input to the catalog site, providing a boundary between image metadata/build definitions and user-facing discovery. The site’s data-generation script produces image data consumed by Astro pages.
Paths: `catalog.json`, `site/scripts/build-data.mjs`, `site/src/data/images.json`

#### Build, publish, and attest pipeline
The central CI workflow builds the catalog on a six-hour cadence and publishes production images. The project’s artifact contract includes keyless Cosign signatures, SPDX SBOM attestations, and SLSA provenance. GHCR is the image distribution service; GitHub Actions OIDC underpins the documented keyless verification model.
Paths: `.github/workflows/build.yml`, `cosign/apko/cosign.yaml`, `.github/SECURITY.md`

#### Security scanning and vulnerability assertions
Grype findings are informational for publication but feed the catalog and GitHub Security reporting. Per-image OpenVEX documents express vulnerability status; repository tooling reconciles them against fresh scans so suppressions remain current. This makes scan output and VEX status distinct security data streams.
Paths: `vex/python.openvex.json`, `tools/vex/reconcile.sh`, `grype/apko/grype.yaml`

#### Update automation and dependency maintenance
Independent automation loops update application versions, rebuild against current Wolfi packages, and patch vulnerable transitive dependencies. Version policy and coverage are represented centrally, while scripts create and manage update PRs. These flows modify image recipes rather than directly changing published artifacts.
Paths: `.github/versions.yaml`, `.github/scripts/check-upstream.sh`, `.github/workflows/patch-deps.yml`

#### Static documentation and catalog delivery
The `site/` subproject is an Astro/TypeScript static site presenting image pages and operational documentation. It consumes generated image data and is deployed independently from the image build workflow, via a dedicated GitHub Actions workflow, to `minimalcontainers.com`.
Paths: `site/package.json`, `site/src/pages/images/[name].astro`, `.github/workflows/deploy-site.yml`

Main entry points: [`.github/workflows/build.yml`](https://github.com/rtvkiz/minimal/blob/main/.github/workflows/build.yml) (Build and publish CI), [`caddy/apko/caddy.yaml`](https://github.com/rtvkiz/minimal/blob/main/caddy/apko/caddy.yaml) (Production image recipe), [`Makefile`](https://github.com/rtvkiz/minimal/blob/main/Makefile) (Make targets), [`catalog.json`](https://github.com/rtvkiz/minimal/blob/main/catalog.json) (Image inventory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_recipes["Image recipes"]
  node_melange["Caddy package recipe<br/>Melange recipe<br/>[melange.yaml]"]
  node_apko_prod["Production image recipe<br/>apko recipe<br/>[caddy.yaml]"]
  node_apko_dev["Development image recipe<br/>apko recipe<br/>[caddy-dev.yaml]"]
  node_cosign["Cosign image recipe<br/>apko recipe<br/>[cosign.yaml]"]
  node_grype["Grype image recipe<br/>apko recipe<br/>[grype.yaml]"]
end

subgraph group_catalog["Catalog and site"]
  node_catalog_json["Image inventory<br/>canonical catalog<br/>[catalog.json]"]
  node_site_data_build["Catalog data generator<br/>Node script<br/>[build-data.mjs]"]
  node_site_data["Generated image data<br/>site data<br/>[images.json]"]
  node_astro_pages["Image catalog pages<br/>Astro pages<br/>[&#91;name&#93;.astro]"]
  node_site_project["Static catalog site<br/>Astro/TypeScript project<br/>[package.json]"]
  node_site_deploy["Site deploy workflow<br/>GitHub Actions workflow<br/>[deploy-site.yml]"]
end

subgraph group_automation["CI and maintenance"]
  node_build_workflow["Build and publish CI<br/>GitHub Actions workflow<br/>[build.yml]"]
  node_ghcr[("GHCR<br/>container registry")]
  node_oidc{{"GitHub Actions OIDC<br/>identity provider"}}
  node_security_doc["Verification guidance<br/>security documentation<br/>[SECURITY.md]"]
  node_vex["OpenVEX assertions<br/>vulnerability status"]
  node_vex_reconcile["VEX reconciliation<br/>security script<br/>[reconcile.sh]"]
  node_versions["Version policy<br/>version manifest<br/>[versions.yaml]"]
  node_upstream_check["Upstream update checks<br/>maintenance script<br/>[check-upstream.sh]"]
  node_patch_deps["Dependency patch workflow<br/>GitHub Actions workflow<br/>[patch-deps.yml]"]
end

node_make["Make targets<br/>developer entry point"]
node_readme["Project guide<br/>documentation<br/>[README.md]"]

node_readme -.->|"documents"| node_make
node_make -->|"builds packages"| node_melange
node_make -->|"assembles images"| node_apko_prod
node_melange -->|"package input"| node_apko_prod
node_apko_prod -.->|"parallel variant"| node_apko_dev
node_catalog_json -->|"defines build matrix"| node_build_workflow
node_build_workflow -->|"builds"| node_apko_prod
node_build_workflow -->|"publishes images"| node_ghcr
node_oidc -->|"keyless identity"| node_build_workflow
node_cosign -->|"signs and attests"| node_build_workflow
node_security_doc -.->|"documents verification"| node_oidc
node_grype -->|"scan findings"| node_vex_reconcile
node_vex -->|"reconciles assertions"| node_vex_reconcile
node_build_workflow -->|"security scanning"| node_grype
node_versions -->|"governs coverage"| node_upstream_check
node_upstream_check -->|"updates recipes"| node_apko_prod
node_patch_deps -->|"patches recipes"| node_apko_prod
node_catalog_json -->|"catalog input"| node_site_data_build
node_site_data_build -->|"generates"| node_site_data
node_site_data -->|"supplies image data"| node_astro_pages
node_site_project -->|"contains"| node_astro_pages
node_site_deploy -->|"deploys"| node_site_project

click node_make "https://github.com/rtvkiz/minimal/blob/main/Makefile"
click node_readme "https://github.com/rtvkiz/minimal/blob/main/README.md"
click node_melange "https://github.com/rtvkiz/minimal/blob/main/caddy/melange.yaml"
click node_apko_prod "https://github.com/rtvkiz/minimal/blob/main/caddy/apko/caddy.yaml"
click node_apko_dev "https://github.com/rtvkiz/minimal/blob/main/caddy/apko/caddy-dev.yaml"
click node_catalog_json "https://github.com/rtvkiz/minimal/blob/main/catalog.json"
click node_build_workflow "https://github.com/rtvkiz/minimal/blob/main/.github/workflows/build.yml"
click node_cosign "https://github.com/rtvkiz/minimal/blob/main/cosign/apko/cosign.yaml"
click node_security_doc "https://github.com/rtvkiz/minimal/blob/main/.github/SECURITY.md"
click node_grype "https://github.com/rtvkiz/minimal/blob/main/grype/apko/grype.yaml"
click node_vex "https://github.com/rtvkiz/minimal/blob/main/vex/python.openvex.json"
click node_vex_reconcile "https://github.com/rtvkiz/minimal/blob/main/tools/vex/reconcile.sh"
click node_versions "https://github.com/rtvkiz/minimal/blob/main/.github/versions.yaml"
click node_upstream_check "https://github.com/rtvkiz/minimal/blob/main/.github/scripts/check-upstream.sh"
click node_patch_deps "https://github.com/rtvkiz/minimal/blob/main/.github/workflows/patch-deps.yml"
click node_site_data_build "https://github.com/rtvkiz/minimal/blob/main/site/scripts/build-data.mjs"
click node_site_data "https://github.com/rtvkiz/minimal/blob/main/site/src/data/images.json"
click node_astro_pages "https://github.com/rtvkiz/minimal/blob/main/site/src/pages/images/%5Bname%5D.astro"
click node_site_project "https://github.com/rtvkiz/minimal/blob/main/site/package.json"
click node_site_deploy "https://github.com/rtvkiz/minimal/blob/main/.github/workflows/deploy-site.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_melange,node_apko_prod,node_apko_dev,node_cosign,node_grype toneBlue
class node_catalog_json,node_site_data_build,node_site_data,node_astro_pages,node_site_project,node_site_deploy toneAmber
class node_build_workflow,node_ghcr,node_oidc,node_security_doc,node_vex,node_vex_reconcile,node_versions,node_upstream_check,node_patch_deps toneMint
class node_make,node_readme toneNeutral
```

## Components

### Image recipes

Per-image package and image definitions.

- [Caddy package recipe](https://github.com/rtvkiz/minimal/blob/main/caddy/melange.yaml): Melange recipe · Builds source-based application packages. · `caddy/melange.yaml`
- [Production image recipe](https://github.com/rtvkiz/minimal/blob/main/caddy/apko/caddy.yaml): apko recipe · `caddy/apko/caddy.yaml`
- [Development image recipe](https://github.com/rtvkiz/minimal/blob/main/caddy/apko/caddy-dev.yaml): apko recipe · `caddy/apko/caddy-dev.yaml`
- [Cosign image recipe](https://github.com/rtvkiz/minimal/blob/main/cosign/apko/cosign.yaml): apko recipe · `cosign/apko/cosign.yaml`
- [Grype image recipe](https://github.com/rtvkiz/minimal/blob/main/grype/apko/grype.yaml): apko recipe · `grype/apko/grype.yaml`

### Catalog and site

Inventory-driven public discovery.

- [Image inventory](https://github.com/rtvkiz/minimal/blob/main/catalog.json): canonical catalog · Declared inventory validated against the CI matrix. · `catalog.json`
- [Catalog data generator](https://github.com/rtvkiz/minimal/blob/main/site/scripts/build-data.mjs): Node script · Generates image data for the static site. · `site/scripts/build-data.mjs`
- [Generated image data](https://github.com/rtvkiz/minimal/blob/main/site/src/data/images.json): site data · `site/src/data/images.json`
- [Image catalog pages](https://github.com/rtvkiz/minimal/blob/main/site/src/pages/images/%5Bname%5D.astro): Astro pages · `site/src/pages/images/[name].astro`
- [Static catalog site](https://github.com/rtvkiz/minimal/blob/main/site/package.json): Astro/TypeScript project · `site/package.json`
- [Site deploy workflow](https://github.com/rtvkiz/minimal/blob/main/.github/workflows/deploy-site.yml): GitHub Actions workflow · Deploys the catalog independently to minimalcontainers.com. · `.github/workflows/deploy-site.yml`

### CI and maintenance

Build, security, publication, and update automation.

- [Build and publish CI](https://github.com/rtvkiz/minimal/blob/main/.github/workflows/build.yml): GitHub Actions workflow · Builds on a six-hour cadence and publishes production images. · `.github/workflows/build.yml`
- **GHCR**: container registry · Distribution endpoint for published images.
- **GitHub Actions OIDC**: identity provider · Supports keyless artifact verification.
- [Verification guidance](https://github.com/rtvkiz/minimal/blob/main/.github/SECURITY.md): security documentation · `.github/SECURITY.md`
- [OpenVEX assertions](https://github.com/rtvkiz/minimal/blob/main/vex/python.openvex.json): vulnerability status · Per-image vulnerability status declarations. · `vex/python.openvex.json`
- [VEX reconciliation](https://github.com/rtvkiz/minimal/blob/main/tools/vex/reconcile.sh): security script · Reconciles VEX assertions with fresh scans. · `tools/vex/reconcile.sh`
- [Version policy](https://github.com/rtvkiz/minimal/blob/main/.github/versions.yaml): version manifest · `.github/versions.yaml`
- [Upstream update checks](https://github.com/rtvkiz/minimal/blob/main/.github/scripts/check-upstream.sh): maintenance script · Creates and manages application-version update PRs. · `.github/scripts/check-upstream.sh`
- [Dependency patch workflow](https://github.com/rtvkiz/minimal/blob/main/.github/workflows/patch-deps.yml): GitHub Actions workflow · Patches vulnerable transitive dependencies through recipe changes. · `.github/workflows/patch-deps.yml`

### Other components

- [Make targets](https://github.com/rtvkiz/minimal/blob/main/Makefile): developer entry point · `Makefile`
- [Project guide](https://github.com/rtvkiz/minimal/blob/main/README.md): documentation · `README.md`

## Connections

- Project guide → Make targets: documents
- Make targets → Caddy package recipe: builds packages
- Make targets → Production image recipe: assembles images
- Caddy package recipe → Production image recipe: package input
- Production image recipe → Development image recipe: parallel variant
- Image inventory → Build and publish CI: defines build matrix
- Build and publish CI → Production image recipe: builds
- Build and publish CI → GHCR: publishes images
- GitHub Actions OIDC → Build and publish CI: keyless identity
- Cosign image recipe → Build and publish CI: signs and attests
- Verification guidance → GitHub Actions OIDC: documents verification
- Grype image recipe → VEX reconciliation: scan findings
- OpenVEX assertions → VEX reconciliation: reconciles assertions
- Build and publish CI → Grype image recipe: security scanning
- Version policy → Upstream update checks: governs coverage
- Upstream update checks → Production image recipe: updates recipes
- Dependency patch workflow → Production image recipe: patches recipes
- Image inventory → Catalog data generator: catalog input
- Catalog data generator → Generated image data: generates
- Generated image data → Image catalog pages: supplies image data
- Static catalog site → Image catalog pages: contains
- Site deploy workflow → Static catalog site: deploys