From ec0766818ee9dda0029f301f9116219f1ccb0282 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 30 Apr 2026 05:10:21 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20[UX=20improvement]=20?=
 =?UTF-8?q?Enhance=20documentation=20DX=20with=20architecture=20diagram=20?=
 =?UTF-8?q?and=20status=20clarity?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR improves the Developer Experience (DX) and accessibility of the project's primary interface (the README):

💡 What:
- Added a Mermaid architecture diagram to visualize the three layers of the system (Cloud Native, Orchestration, Infrastructure).
- Replaced the small "Experimental" badge with a high-visibility GitHub Caution Alert.
- Improved the License badge alt-text.

🎯 Why:
- Architecture diagrams significantly reduce the time-to-understanding for complex infrastructure projects.
- The caution alert ensures users are immediately aware of the experimental status, improving safety.
- Descriptive alt-text is a key accessibility requirement for screen reader users.

♿ Accessibility:
- Updated badge alt-text from "License: MIT" to "License: MIT - Open source software license".

Co-authored-by: igor-holt <125706350+igor-holt@users.noreply.github.com>
---
 README.md | 36 ++++++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 80d6c39..5367adf 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
 # ⚖️ 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 - Open source software license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> [!CAUTION]
+> This project is experimental and not recommended for production use. It involves bare-metal hardware management and quantum-accelerated scheduling which are currently in active development.
 
 Dual nature—combining bare-metal virtualized hardware management (aSHARD VRAM pinning) with quantum-accelerated Kubernetes scheduling.
 
@@ -16,6 +18,36 @@ 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 Cloud_Native [Cloud Native Layer]
+        K8S[Kubernetes Cluster]
+        Workloads[AI/ML Workloads]
+    end
+
+    subgraph Orchestration [Orchestration Layer]
+        Arbiter((Arbiter Core))
+        Scheduler[Quantum-Accelerated Scheduler]
+    end
+
+    subgraph Infrastructure [Infrastructure Layer]
+        Metal[Bare-Metal Hardware]
+        GPU[GPU Resources]
+        vRAM[aSHARD VRAM Pinning]
+    end
+
+    Workloads --> K8S
+    K8S <--> Scheduler
+    Scheduler --- Arbiter
+    Arbiter <--> vRAM
+    vRAM --- GPU
+    GPU --- Metal
+
+    style Arbiter fill:#f96,stroke:#333,stroke-width:4px
+```
+
 ## ⚖️ License
 
 This project is licensed under the [MIT License](LICENSE).