diff --git a/README.md b/README.md
index b6b101f..27507a2 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,10 @@ This is useful in the following scenarios:
Peerd is compatible with Azure Container Registry's [Artifact Streaming][ACR Artifact Streaming] feature, and can be
used to improve performance further.
+ | **Without Peerd** | **With Peerd** |
+ | --------------------------- | -------------------------- |
+ | ![normal-streaming-summary] | ![peerd-streaming-summary] |
+
* **Peer to Peer Container Image Pulls**: Pulling a container image to a node in Kubernetes is often a time consuming
process, especially in scenarios where the registry becomes a bottleneck, such as deploying a large cluster or scaling
out in response to bursty traffic. To increase throughput, nodes in the cluster which already have the image can be
@@ -72,6 +76,10 @@ This is useful in the following scenarios:
of the registry. Containerd has a [mirror][containerd hosts] facility that can be used to configure Peerd as the
mirror for container images.
+ | **Without Peerd** | **With Peerd** |
+ | ---------------------- | --------------------- |
+ | ![normal-pull-summary] | ![peerd-pull-summary] |
+
The APIs are described in the [swagger.yaml].
## Quickstart
@@ -178,3 +186,7 @@ integration with [Overlaybd].
[peerd-pkgs]: https://github.com/Azure/peerd/pkgs/container/acr%2Fdev%2Fpeerd
[build.md]: ./docs/build.md
[values.yml]: ./build/package/peerd-helm/values.yaml
+[normal-pull-summary]: ./assets/mermaid/rendered/normal-pull-summary.png
+[peerd-pull-summary]: ./assets/mermaid/rendered/peerd-pull-summary.png
+[normal-streaming-summary]: ./assets/mermaid/rendered/normal-streaming-summary.png
+[peerd-streaming-summary]: ./assets/mermaid/rendered/peerd-streaming-summary.png
diff --git a/assets/images/cluster.drawio b/assets/images/cluster.drawio
deleted file mode 100644
index 0ba98e8..0000000
--- a/assets/images/cluster.drawio
+++ /dev/null
@@ -1,85 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/assets/mermaid/normal-pull-summary.md b/assets/mermaid/normal-pull-summary.md
new file mode 100644
index 0000000..54e103c
--- /dev/null
+++ b/assets/mermaid/normal-pull-summary.md
@@ -0,0 +1,58 @@
+graph TD;
+ subgraph Cluster[Normal Image Pull in a Kubernetes Cluster]
+ subgraph ctr-1[Containerd]
+ subgraph store-1["Content Store"]
+ sl-2[sha256:l2]
+ end
+ end
+
+ subgraph ctr-2[Containerd]
+ subgraph store-2["Content Store"]
+ sl-6[sha256:l6]
+ sl-3[sha256:l3]
+ end
+ end
+
+ subgraph ctr-3[Containerd]
+ subgraph store-3["Content Store"]
+ sl-4[sha256:l4]
+ sl-5[sha256:l5]
+ end
+ end
+
+ subgraph Node1[Node A]
+ direction TB
+ kubelet["kubectl run mcr.microsoft.com/nginx:latest"]
+ ctr-1
+
+ kubelet ~~~ ctr-1
+ end
+
+ subgraph Node2[Node B]
+ ctr-2
+ end
+
+ subgraph Node3[Node C]
+ ctr-3
+ end
+ end
+
+ subgraph Upstream[Upstream Container Registry]
+ acr(mcr.microsoft.com)
+ end
+
+ Node1 --> |GET sha256:l6| acr
+ Node1 --> |GET sha256:l3| acr
+ Node1 --> |GET sha256:l4| acr
+ Node1 --> |GET sha256:l5| acr
+ Node1 --> |GET sha256:l1| acr
+ Node1 --> |GET sha256:c1| acr
+
+ classDef cluster fill:#fafafa,stroke:#bbb,stroke-width:2px,color:#326ce5;
+ class Node1,NodeN cluster
+
+ classDef registry fill:#e0f7fa,stroke:#00008b,stroke-width:2px,color:#326ce5;
+ class acr registry
+
+ classDef outer fill:#e0f7fa,stroke:#00008b,stroke-width:2px,color:#a9a9a9;
+ class Cluster outer
diff --git a/assets/mermaid/normal-streaming-summary.md b/assets/mermaid/normal-streaming-summary.md
new file mode 100644
index 0000000..36cf221
--- /dev/null
+++ b/assets/mermaid/normal-streaming-summary.md
@@ -0,0 +1,58 @@
+graph TD;
+ subgraph Cluster[Normal Image Streaming in a Kubernetes Cluster]
+ subgraph fs-1[Filesystem]
+ subgraph store-1["Files"]
+ sf-2[sha256:l2, bytes=10-4500]
+ end
+ end
+
+ subgraph fs-2[Filesystem]
+ subgraph store-2["Files"]
+ sf-6[sha256:l6, bytes=100-1000]
+ sf-3[sha256:l3, bytes=0-10000]
+ end
+ end
+
+ subgraph fs-3[Filesystem]
+ subgraph store-3["Files"]
+ sf-4[sha256:l4, bytes=90-1000]
+ sf-5[sha256:l5, bytes=0-700]
+ end
+ end
+
+ subgraph Node1[Node A]
+ direction TB
+ kubelet["kubectl run mcr.microsoft.com/nginx:streamable"]
+ fs-1
+
+ kubelet ~~~ fs-1
+ end
+
+ subgraph Node2[Node B]
+ fs-2
+ end
+
+ subgraph Node3[Node C]
+ fs-3
+ end
+ end
+
+ subgraph Upstream[Upstream Container Registry]
+ acr(mcr.microsoft.com)
+ end
+
+ Node1 --> |GET sha256:l6
bytes=101-500| acr
+ Node1 --> |GET sha256:l3
bytes10-790| acr
+ Node1 --> |GET sha256:l4
bytes=91-500| acr
+ Node1 --> |GET sha256:l5
bytes=0-700| acr
+ Node1 --> |GET sha256:l1
bytes=800-9000| acr
+ Node1 --> |GET sha256:c1
bytes=0-10000| acr
+
+ classDef cluster fill:#fafafa,stroke:#bbb,stroke-width:2px,color:#326ce5;
+ class Node1,NodeN cluster
+
+ classDef registry fill:#e0f7fa,stroke:#00008b,stroke-width:2px,color:#326ce5;
+ class acr registry
+
+ classDef outer fill:#e0f7fa,stroke:#00008b,stroke-width:2px,color:#a9a9a9;
+ class Cluster outer
diff --git a/assets/mermaid/peerd-pull-summary.md b/assets/mermaid/peerd-pull-summary.md
new file mode 100644
index 0000000..04d8354
--- /dev/null
+++ b/assets/mermaid/peerd-pull-summary.md
@@ -0,0 +1,87 @@
+graph TD;
+ subgraph Cluster[Peer to Peer Image Pull in a Kubernetes Cluster]
+ subgraph ctr-1[Containerd]
+ subgraph store-1["Content Store"]
+ sl-2[sha256:l2]
+ end
+ end
+
+ subgraph ctr-2[Containerd]
+ subgraph store-2["Content Store"]
+ sl-6[sha256:l6]
+ sl-3[sha256:l3]
+ end
+ end
+
+ subgraph ctr-3[Containerd]
+ subgraph store-3["Content Store"]
+ sl-4[sha256:l4]
+ sl-5[sha256:l5]
+ end
+ end
+
+ subgraph Node1[Node A]
+ direction TB
+ kubelet["kubectl run mcr.microsoft.com/nginx:latest"]
+ ctr-1
+
+ kubelet ~~~ ctr-1
+ end
+
+ subgraph Node2[Node B]
+ ctr-2
+ end
+
+ subgraph Node3[Node C]
+ ctr-3
+ end
+ end
+
+ subgraph manifest-1[mcr.microsft.com/nginx@sha256:m1]
+ direction TB
+ c-1[config sha256:c1]
+ l-1[layer sha256:l1]
+ l-2[layer sha256:l2]
+ l-3[layer sha256:l3]
+ l-4[layer sha256:l4]
+ l-5[layer sha256:l5]
+ l-6[layer sha256:l6]
+
+ c-1 ~~~ l-1
+ l-1 ~~~ l-2
+ l-2 ~~~ l-3
+ l-3 ~~~ l-4
+ l-4 ~~~ l-5
+ l-5 ~~~ l-6
+ end
+
+ subgraph Upstream[Upstream Container Registry]
+ acr(mcr.microsoft.com)
+ end
+
+ subgraph Legend[Legend]
+ direction TB
+ mtls[Pull from Peer - mTLS connections]
+ tls[Pull from Upstream - TLS connections]
+
+ mtls ~~~ tls
+ end
+
+ Legend ~~~ Upstream
+
+ Node1 -.-> |
GET sha256:l6| sl-6
+ Node1 -.-> |
GET sha256:l3| sl-3
+ Node1 -.-> |
GET sha256:l4| sl-4
+ Node1 -.-> |
GET sha256:l5| sl-5
+
+ Node1 --> |
GET sha256:l1| acr
+ Node1 --> |
GET sha256:c1| acr
+
+ classDef cluster fill:#fafafa,stroke:#bbb,stroke-width:2px,color:#326ce5;
+ class Node1,NodeN cluster
+
+ classDef registry fill:#e0f7fa,stroke:#00008b,stroke-width:2px,color:#326ce5;
+ class acr registry
+
+ classDef outer fill:#e0f7fa,stroke:#00008b,stroke-width:2px,color:#a9a9a9;
+ class Cluster outer
diff --git a/assets/mermaid/peerd-streaming-summary.md b/assets/mermaid/peerd-streaming-summary.md
new file mode 100644
index 0000000..8cd8e26
--- /dev/null
+++ b/assets/mermaid/peerd-streaming-summary.md
@@ -0,0 +1,88 @@
+graph TD;
+ subgraph Cluster[Peer to Peer Image Streaming in a Kubernetes Cluster]
+ subgraph fs-1[Filesystem]
+ subgraph store-1["Files"]
+ sf-2[sha256:l2, bytes=10-4500]
+ end
+ end
+
+ subgraph fs-2[Filesystem]
+ subgraph store-2["Files"]
+ sf-6[sha256:l6, bytes=100-1000]
+ sf-3[sha256:l3, bytes=0-10000]
+ end
+ end
+
+ subgraph fs-3[Filesystem]
+ subgraph store-3["Files"]
+ sf-4[sha256:l4, bytes=90-1000]
+ sf-5[sha256:l5, bytes=0-700]
+ sf-1[sha256:l1, bytes=0-10000]
+ end
+ end
+
+ subgraph Node1[Node A]
+ direction TB
+ kubelet["kubectl run mcr.microsoft.com/nginx:streamable"]
+ fs-1
+
+ kubelet ~~~ fs-1
+ end
+
+ subgraph Node2[Node B]
+ fs-2
+ end
+
+ subgraph Node3[Node C]
+ fs-3
+ end
+ end
+
+ subgraph manifest-1[mcr.microsft.com/nginx@sha256:m2]
+ direction TB
+ c-1[config sha256:c1]
+ l-1[layer sha256:l1]
+ l-2[layer sha256:l2]
+ l-3[layer sha256:l3]
+ l-4[layer sha256:l4]
+ l-5[layer sha256:l5]
+ l-6[layer sha256:l6]
+
+ c-1 ~~~ l-1
+ l-1 ~~~ l-2
+ l-2 ~~~ l-3
+ l-3 ~~~ l-4
+ l-4 ~~~ l-5
+ l-5 ~~~ l-6
+ end
+
+ subgraph Upstream[Upstream Container Registry]
+ acr(mcr.microsoft.com)
+ end
+
+ subgraph Legend[Legend]
+ direction TB
+ mtls[Pull from Peer - mTLS connections]
+ tls[Pull from Upstream - TLS connections]
+
+ mtls ~~~ tls
+ end
+
+ Legend ~~~ Upstream
+
+ Node1 --> |GET sha256:l6
bytes=101-500| sf-6
+ Node1 --> |GET sha256:l3
bytes10-790| sf-3
+ Node1 --> |GET sha256:l4
bytes=91-500| sf-4
+ Node1 --> |GET sha256:l5
bytes=0-700| sf-5
+ Node1 --> |GET sha256:l1
bytes=800-9000| sf-1
+
+ Node1 --> |GET sha256:c1
bytes=0-10000| acr
+
+ classDef cluster fill:#fafafa,stroke:#bbb,stroke-width:2px,color:#326ce5;
+ class Node1,NodeN cluster
+
+ classDef registry fill:#e0f7fa,stroke:#00008b,stroke-width:2px,color:#326ce5;
+ class acr registry
+
+ classDef outer fill:#e0f7fa,stroke:#00008b,stroke-width:2px,color:#a9a9a9;
+ class Cluster outer
diff --git a/assets/mermaid/rendered/normal-pull-summary.png b/assets/mermaid/rendered/normal-pull-summary.png
new file mode 100644
index 0000000..302c25f
Binary files /dev/null and b/assets/mermaid/rendered/normal-pull-summary.png differ
diff --git a/assets/mermaid/rendered/normal-streaming-summary.png b/assets/mermaid/rendered/normal-streaming-summary.png
new file mode 100644
index 0000000..ad8db11
Binary files /dev/null and b/assets/mermaid/rendered/normal-streaming-summary.png differ
diff --git a/assets/mermaid/rendered/peerd-pull-summary.png b/assets/mermaid/rendered/peerd-pull-summary.png
new file mode 100644
index 0000000..cba0922
Binary files /dev/null and b/assets/mermaid/rendered/peerd-pull-summary.png differ
diff --git a/assets/mermaid/rendered/peerd-streaming-summary.png b/assets/mermaid/rendered/peerd-streaming-summary.png
new file mode 100644
index 0000000..ae82d7d
Binary files /dev/null and b/assets/mermaid/rendered/peerd-streaming-summary.png differ