From 24d3062bb6957a4e501dd15a48b3b029fc1a64cc Mon Sep 17 00:00:00 2001
From: Artem Ukrainskii <temicska99@mail.ru>
Date: Mon, 7 Sep 2026 00:53:47 +0300
Subject: [PATCH 1/4] docs: move sync architecture diagram

---
 docs/architecture.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 docs/architecture.md

diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..6c93582
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,40 @@
+# Architecture
+
+**cloud-secrets** continuously synchronizes secrets from an external secret manager into Docker Swarm, creates versioned Docker Secrets when values change, and rolls affected services onto the new secret version.
+
+The diagram below shows the full synchronization lifecycle.
+
+```mermaid
+flowchart TD
+    A[cloud-secrets starts] --> B[Load config from env vars]
+    B --> C["Create Docker Swarm<br/>and Cloud clients"]
+    C --> E[Application sync loop]
+
+    F[Trigger by timer] --> E
+    Q[Trigger by SIGHUP] --> E
+
+    E --> G[Read secrets from Cloud]
+    E --> H[Read secrets from Swarm]
+    G --> I["Compare by logical path<br/>and external version id"]
+    H --> I
+
+    I --> J{Secret state in Swarm}
+    J -->|not exists| K[Create new Swarm secret]
+    J -->|version changed| L[Create new secret version]
+    J -->|same version| M[Skip]
+
+    L --> N["Update services to use new secret ID"]
+    N --> R[Rolls updated service tasks]
+    R --> O[Remove old versions]
+    O --> S[Restore parent secret]
+    S --> T["Reload Swarm state"]
+    T --> U{"CS_CLEANUP_ORPHANED=true"}
+    U -->|yes| V["Remove managed secrets absent in Cloud<br/>and unused by services, with all versions"]
+    U -->|no| P
+
+    K --> P[Write sync result logs]
+    V --> P
+    M --> P
+```
+
+[Back to README](../README.md)

From 0ed3371880f0342cc9486a8d289cf44294d86172 Mon Sep 17 00:00:00 2001
From: Artem Ukrainskii <temicska99@mail.ru>
Date: Mon, 7 Sep 2026 00:53:59 +0300
Subject: [PATCH 2/4] docs: simplify README architecture overview

---
 README.md | 36 ++++++------------------------------
 1 file changed, 6 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index 6ee8e9a..b798825 100644
--- a/README.md
+++ b/README.md
@@ -11,38 +11,14 @@ Supported cloud providers:
 ## How it works
 
 ```mermaid
-flowchart TD
-    A[cloud-secrets starts] --> B[Load config from env vars]
-    B --> C["Create Docker Swarm<br/>and Cloud clients"]
-    C --> E[Application sync loop]
-
-    F[Trigger by timer] --> E
-    Q[Trigger by SIGHUP] --> E
-
-    E --> G[Read secrets from Cloud]
-    E --> H[Read secrets from Swarm]
-    G --> I["Compare by logical path<br/>and external version id"]
-    H --> I
-
-    I --> J{Secret state in Swarm}
-    J -->|not exists| K[Create new Swarm secret]
-    J -->|version changed| L[Create new secret version]
-    J -->|same version| M[Skip]
-
-    L --> N["Update services to use new secret ID"]
-    N --> R[Rolls updated service tasks]
-    R --> O[Remove old versions]
-    O --> S[Restore parent secret]
-    S --> T["Reload Swarm state"]
-    T --> U{"CS_CLEANUP_ORPHANED=true"}
-    U -->|yes| V["Remove managed secrets absent in Cloud<br/>and unused by services, with all versions"]
-    U -->|no| P
-
-    K --> P[Write sync result logs]
-    V --> P
-    M --> P
+flowchart LR
+    A[External Secret Manager] --> B[cloud-secrets]
+    B --> C[Docker Secrets]
+    C --> D[Swarm Services]
 ```
 
+See [Architecture](./docs/architecture.md) for the full synchronization lifecycle.
+
 ## Design goals
 
 - External secret manager is the source of truth

From 343d913e5cfd799fe6afd4f447806fc47563f8ec Mon Sep 17 00:00:00 2001
From: Artem Ukrainskii <temicska99@mail.ru>
Date: Mon, 7 Sep 2026 00:57:31 +0300
Subject: [PATCH 3/4] docs: add static architecture overview

---
 docs/architecture-overview.svg | 86 ++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 docs/architecture-overview.svg

diff --git a/docs/architecture-overview.svg b/docs/architecture-overview.svg
new file mode 100644
index 0000000..5af9181
--- /dev/null
+++ b/docs/architecture-overview.svg
@@ -0,0 +1,86 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="120" viewBox="0 0 760 120" role="img" aria-labelledby="title desc">
+  <title id="title">cloud-secrets synchronization flow</title>
+  <desc id="desc">External Secret Manager flows through cloud-secrets into Docker Secrets and then Swarm Services.</desc>
+
+  <style>
+    .node {
+      fill: #f6f8fa;
+      stroke: #8c959f;
+      stroke-width: 1.5;
+    }
+
+    .node-primary {
+      fill: #dafbe1;
+      stroke: #1a7f37;
+      stroke-width: 1.5;
+    }
+
+    .label {
+      fill: #24292f;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+      font-size: 14px;
+      font-weight: 600;
+      text-anchor: middle;
+      dominant-baseline: middle;
+    }
+
+    .arrow {
+      fill: none;
+      stroke: #57606a;
+      stroke-width: 1.5;
+      marker-end: url(#arrowhead);
+    }
+
+    .arrowhead {
+      fill: #57606a;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      .node {
+        fill: #161b22;
+        stroke: #6e7681;
+      }
+
+      .node-primary {
+        fill: #12261a;
+        stroke: #3fb950;
+      }
+
+      .label {
+        fill: #f0f6fc;
+      }
+
+      .arrow {
+        stroke: #8b949e;
+      }
+
+      .arrowhead {
+        fill: #8b949e;
+      }
+    }
+  </style>
+
+  <defs>
+    <marker id="arrowhead" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto" markerUnits="strokeWidth">
+      <path class="arrowhead" d="M0,0 L8,4 L0,8 Z"/>
+    </marker>
+  </defs>
+
+  <rect class="node" x="10" y="35" width="180" height="50" rx="8"/>
+  <text class="label" x="100" y="60">External Secret Manager</text>
+
+  <path class="arrow" d="M190 60 H220"/>
+
+  <rect class="node-primary" x="230" y="35" width="140" height="50" rx="8"/>
+  <text class="label" x="300" y="60">cloud-secrets</text>
+
+  <path class="arrow" d="M370 60 H400"/>
+
+  <rect class="node" x="410" y="35" width="140" height="50" rx="8"/>
+  <text class="label" x="480" y="60">Docker Secrets</text>
+
+  <path class="arrow" d="M550 60 H580"/>
+
+  <rect class="node" x="590" y="35" width="160" height="50" rx="8"/>
+  <text class="label" x="670" y="60">Swarm Services</text>
+</svg>

From e538ad950be40956dd4fd77fd2b4030bbac64080 Mon Sep 17 00:00:00 2001
From: Artem Ukrainskii <temicska99@mail.ru>
Date: Mon, 7 Sep 2026 00:57:37 +0300
Subject: [PATCH 4/4] docs: use static architecture diagram in README

---
 README.md | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index b798825..5e9dbd8 100644
--- a/README.md
+++ b/README.md
@@ -10,12 +10,9 @@ Supported cloud providers:
 
 ## How it works
 
-```mermaid
-flowchart LR
-    A[External Secret Manager] --> B[cloud-secrets]
-    B --> C[Docker Secrets]
-    C --> D[Swarm Services]
-```
+<p align="center">
+  <img src="./docs/architecture-overview.svg" alt="External Secret Manager → cloud-secrets → Docker Secrets → Swarm Services" width="760" />
+</p>
 
 See [Architecture](./docs/architecture.md) for the full synchronization lifecycle.