From ec0805f1a10fae6ebc6941b4a4c597df5efb6bd4 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 19 May 2026 05:30:28 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20Add=20architecture=20?=
 =?UTF-8?q?diagram=20and=20accessibility=20titles=20to=20README?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Added a Mermaid architecture diagram to visualize the orchestration layers (Cloud-Native, Orchestration, Infrastructure).
- Added descriptive `title` attributes to project badges for improved accessibility and hover tooltips.
- Updated Palette's journal with learnings on documentation UX for orchestration projects.

Co-authored-by: igor-holt <125706350+igor-holt@users.noreply.github.com>
---
 .Jules/palette.md |  5 +++++
 README.md         | 30 ++++++++++++++++++++++++++++--
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/.Jules/palette.md b/.Jules/palette.md
index fecc08d..a4551e5 100644
--- a/.Jules/palette.md
+++ b/.Jules/palette.md
@@ -6,3 +6,8 @@ This journal contains critical UX/accessibility learnings discovered during the
 **Learning:** For infrastructure or backend projects without a functional frontend, the `README.md` serves as the primary User Experience (DX/UX). In these cases, micro-UX improvements shift from ARIA labels to scannability, clarity of project status, and informative (non-redundant) feature lists.
 
 **Action:** Treat the `README.md` as the landing page. Use visual status indicators (badges), scannable bullet points with representative emojis, and ensure that headers provide a clear path for the user to understand the project's utility and maturity.
+
+## 2026-05-19 - Visualizing Architecture for Orchestration UX
+**Learning:** In orchestration-focused repositories (like `arbiter`), the most impactful DX/UX improvement is often a high-level architecture diagram. It provides immediate cognitive alignment for users trying to understand the project's placement within a complex stack (e.g., between Kubernetes and Bare-Metal).
+
+**Action:** Use Mermaid diagrams with consistent visual styling (subgraphs for layers, specific node shapes for core components) to communicate system boundaries and data flow in the README.
diff --git a/README.md b/README.md
index 80d6c39..b2c6b69 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # ⚖️ arbiter
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-![Status: Experimental](https://img.shields.io/badge/Status-Experimental-orange)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg "License: MIT - Open source software license")](https://opensource.org/licenses/MIT)
+![Status: Experimental](https://img.shields.io/badge/Status-Experimental-orange "Project Status: Experimental - Not recommended for production")
 
 Dual nature—combining bare-metal virtualized hardware management (aSHARD VRAM pinning) with quantum-accelerated Kubernetes scheduling.
 
@@ -16,6 +16,32 @@ Dual nature—combining bare-metal virtualized hardware management (aSHARD VRAM
 - ⚛️ **Next-Gen Scheduling**: Leverages quantum-accelerated algorithms for complex Kubernetes workloads.
 - ⚖️ **Unified Orchestration**: A single control plane for both hardware and cluster-level operations.
 
+## 🗺️ Architecture
+
+```mermaid
+graph TD
+    subgraph CloudNative [Cloud-Native Layer]
+        K8s[Kubernetes Cluster]
+        Workloads[AI Workloads]
+    end
+
+    subgraph Orchestration [Orchestration Layer]
+        Arbiter((Arbiter Core))
+    end
+
+    subgraph Infrastructure [Infrastructure Layer]
+        BareMetal[Bare-Metal Hardware]
+        GPU[GPU / aSHARD VRAM]
+    end
+
+    K8s <--> Arbiter
+    Workloads <--> Arbiter
+    Arbiter <--> BareMetal
+    Arbiter <--> GPU
+
+    style Arbiter fill:#f96,stroke-width:4px
+```
+
 ## ⚖️ License
 
 This project is licensed under the [MIT License](LICENSE).