From 90af86e5500af25bed991262fca323647760d48c Mon Sep 17 00:00:00 2001
From: Ryan Brainard <966764+ryanbrainard@users.noreply.github.com>
Date: Tue, 14 Nov 2023 22:16:52 -0500
Subject: [PATCH] Heroku-CNB Image Relationships in Mermaid

---
 README.md                           |  4 +--
 docs/image-relationships-diagram.md | 38 +++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 docs/image-relationships-diagram.md

diff --git a/README.md b/README.md
index 4a91b52c..e970cf49 100644
--- a/README.md
+++ b/README.md
@@ -2,10 +2,10 @@
 
 [![CI](https://github.com/heroku/cnb-builder-images/actions/workflows/build-test-publish.yml/badge.svg)](https://github.com/heroku/cnb-builder-images/actions/workflows/build-test-publish.yml)
 
-This repository is responsible for building and publishing [Cloud Native Buildpacks](https://buildpacks.io)
+This repository is responsible for building and publishing [Cloud Native Buildpacks (CNB)](https://buildpacks.io)
 builders that enable Heroku-like builds with the [`pack`](https://github.com/buildpacks/pack) command.
 
-The builder images use Heroku's [stack images](https://github.com/heroku/stack-images) as their base.
+The builder images use Heroku's [stack images](https://github.com/heroku/stack-images) as their base. To better understand the relationship between these images and the [CNB concepts](https://buildpacks.io/docs/concepts/#what-is-a-builder), see the [Heroku-CNB Image Relationships](docs/image-relationships-diagram.md) diagram.
 
 | Builder Image                                       | Base Image                                  | Status      |
 |-----------------------------------------------------|---------------------------------------------|-------------|
diff --git a/docs/image-relationships-diagram.md b/docs/image-relationships-diagram.md
new file mode 100644
index 00000000..eb5467e5
--- /dev/null
+++ b/docs/image-relationships-diagram.md
@@ -0,0 +1,38 @@
+```mermaid
+---
+title: Heroku-CNB Image Relationships
+---
+graph TB
+    subgraph HIF["Heroku 22 Image Family"]
+        direction LR
+        HIF_CNB_BUILDER("CNB Builder Image\n heroku/builder:22") --> HIF_CNB_BUILD
+        HIF_CNB_BUILD("CNB Build Stack Image\n heroku/heroku:22-cnb-build") --> HIF_H_BUILD
+        HIF_H_BUILD("Heroku Build Stack Image\n heroku/heroku:22-build") --> HIF_H_RUN
+        HIF_CNB_RUN("CNB Runtime Stack Image\n heroku/heroku:22-cnb") --> HIF_H_RUN
+        HIF_H_RUN("Heroku Runtime Stack Image\n heroku/heroku:22") --> HIF_BASE
+        HIF_BASE("Ubuntu Base Image\n ubuntu:22.04")
+    end
+    
+    subgraph CNB["Cloud Native Buildpack Concepts"]
+        direction LR
+        subgraph CNB_BUILDER_IMG["builder image"]
+            direction TB
+            CNB_BUILDER_IMG_BP1("buildpack 1") --> CNB_BUILDER_IMG_BP2
+            CNB_BUILDER_IMG_BP2("buildpack 2") --> CNB_BUILDER_IMG_LC
+            CNB_BUILDER_IMG_LC("lifecycle") --> CNB_BUILDER_IMG_BUILD
+            CNB_BUILDER_IMG_BUILD("build image")
+        end
+
+        subgraph CNB_APP_IMG["app image"]
+            direction TB
+            CNB_APP_IMG_BP1("bp1-provided layers") --> CNB_APP_IMG_BP2
+            CNB_APP_IMG_BP2("bp2-provided layers") --> CNB_APP_IMG_APP
+            CNB_APP_IMG_APP("app layers") --> CNB_APP_IMG_RUN
+            CNB_APP_IMG_RUN("run image")
+        end
+    end
+    
+    HIF_CNB_BUILDER o-.-o CNB_BUILDER_IMG
+    HIF_CNB_BUILD o-.-o CNB_BUILDER_IMG_BUILD
+    HIF_CNB_RUN o-.-o CNB_APP_IMG_RUN
+```
\ No newline at end of file