docs(readme): add Mermaid architecture diagram of fork-specific enhancements

Author: Eidmantas Ivanauskas

README.md

@@ -193,3 +193,82 @@ Notes
 
 - Combined effects (scheduler + limits)
   - Higher `--max-concurrency` with `--per-repo-cap` and `--cooldown` improves fleet throughput and fairness while avoiding monorepo starvation.
+
+## Enhanced runtime architecture (fork-specific)
+
+This diagram shows how our improvements compose when running with the recommended flags (e.g., `--mode=continuous`, `--max-concurrency=0`, `--schedule=lru|fail-first`, `--cooldown`, `--per-repo-cap`, with `REGISTRY_JWT_*` retries enabled).
+
+```mermaid
+flowchart LR
+  subgraph Scheduler[Scheduler]
+    S1[--mode=continuous] --> S2[Per-app timers (interval)]
+    S1 --> S3[Auto concurrency (--max-concurrency=0)]
+    S1 --> S4[Priorities (--schedule=lru|fail-first)]
+    S1 --> S5[Cooldown (--cooldown)]
+    S1 --> S6[Fairness cap (--per-repo-cap)]
+  end
+
+  S2 --> WQ[Worker Pool]
+  S3 --> WQ
+  S4 --> WQ
+  S5 --> WQ
+  S6 --> WQ
+
+  subgraph Worker[Worker (per app)]
+    W1[Compute image candidates] --> W2[Registry operations]
+    W1 --> W3[Spec patch in-memory]
+    W3 -->|WriteBackGit| W4[enqueue writeIntent(repo)]
+    W3 -->|WriteBack Argo CD API| W5[Update via ArgoCD API]
+  end
+
+  WQ --> W1
+
+  %% Registry client path
+  subgraph RegistryClient[Registry client (per registry endpoint)]
+    RC1[Dedicated http.Transport cache\nkeep-alive + sane timeouts\nMaxConnsPerHost cap] --> RC2[rateLimit transport\nper-registry in-flight cap]
+    RC2 --> RC3[singleflight(tags, manifests)]
+    RC3 --> RC4[JWT auth interceptor\n singleflight + retries\n REGISTRY_JWT_*]
+    RC4 --> RC5[HTTPS (HTTP/2 when available)]
+  end
+
+  W2 --> RegistryClient
+
+  %% Batched Git writer path
+  subgraph GitWriter[Per-repo batched writer]
+    GW1[intent queue (repo)] --> GW2[group by branch]
+    GW2 --> GW3[commitBatch]
+    GW3 --> GW4[Git client (fetch/checkout/commit/push)\nretries + backoff]
+  end
+
+  W4 --> GitWriter
+
+  %% Metrics and logging
+  subgraph Metrics[Prometheus metrics]
+    M1[App timings\n(last attempt/success, duration)]
+    M2[Cycle timings]
+    M3[Registry health\n(in-flight, duration, status, retries, errors)]
+    M4[JWT auth\n(requests, errors, duration, TTL)]
+    M5[Singleflight effectiveness]
+  end
+
+  Worker --> M1
+  Scheduler --> M2
+  RegistryClient --> M3
+  RegistryClient --> M4
+  RegistryClient --> M5
+  GitWriter --> M1
+```
+
+Key behaviors added vs upstream:
+
+- Continuous scheduling: per-app timers remove whole-cycle stalls; auto concurrency scales workers.
+- Fairness: `--per-repo-cap` and `--cooldown` prevent hot monorepos from starving others.
+- Registry resiliency and efficiency:
+  - Reused transports with tuned timeouts limit dials and hangs.
+  - Per-registry in-flight cap stops connection storms/port exhaustion.
+  - Singleflight for tags/manifests and JWT auth dedupes bursts.
+  - JWT auth retries with backoff (config via `REGISTRY_JWT_*`).
+  - HTTP/2 when using HTTPS reduces socket pressure under load.
+- Git throughput: per-repo batched writer coalesces multiple app changes per branch into 1 commit+push; Git ops have retries.
+- Clear logs: startup settings, continuous start/finish, queued write-backs.
+- Expanded metrics: deep visibility for scheduling, registry/JWT, and Git paths.