Add artifact.visualization/README.md

artifact.visualization/README.md

@@ -0,0 +1,81 @@
+# Run #17 Gate Visualization UI
+
+## Zweck
+Diese Web-UI dient zur **Visualisierung der Retry-Statistiken** aus *Run #17* und zur **Bewertung der Stabilität der Gate-V1-Implementierung** im *Default-Modus (MODE=warn)*. Sie ist Teil der kontinuierlichen Analysepipeline und liefert Kennzahlen über Wiederholungsversuche, Latenzverteilungen und interne Heuristik-Leistungsindikatoren.
+
+## Hauptfunktionen
+- **Abrufen von Retry-Statistiken** über den API-Endpunkt `/api/retry-stats`
+- **Darstellung zentraler Metriken**: Δt < 0, warn_rate, unknown_rate, healing_rate
+- **Performance-Messung** durch Anzeige von p95 und p99
+- **Interaktive Filterung** nach Stratum und Policy-Konfigurationen
+- **Zustandserkennung und Gate-Zusammenfassung** (Anzeigen von Mode="warn")
+- **Dynamische Aktualisierung** der Visualisierungen bei Nutzerinteraktion
+- **Responsive Dashboard-Struktur**, optimiert für Desktop und Mobile
+
+## Datenfluss
+1. Beim Start ruft das Frontend über `GET /api/retry-stats` die aktuellen Statistikdaten ab.
+2. Die Antwort wird als JSON ausgewertet und an die Visualisierungs-Module im JS-Frontend übergeben.
+3. Diagramme, Kennzahlen und Zusammenfassungen werden im UI dynamisch aktualisiert.
+4. Änderungen der Filtereinstellungen führen zu einem erneuten Datenabruf.
+
+### Erwarteter Response-Shape
+```json
+{
+  "p95": number,
+  "p99": number,
+  "unknown_rate": number,
+  "healing_rate": number,
+  "stats": [
+    {
+      "stratum": string,
+      "policy_hash": string,
+      "dt_lt0": number,
+      "warn_rate": number,
+      "timestamp": string
+    }
+  ]
+}
+```
+
+## API-Nutzung
+**Endpunkt:** `/api/retry-stats`
+
+**Methode:** `GET`
+
+**Optionale Query-Parameter:**
+- `stratum`: Auswahl des gewünschten Stratum
+- `policy_hash`: Filter nach Policy-Konfiguration
+
+**Nutzung im Code:**
+- Definiert in `js/api.js`
+- Wird in der Anwendung beim Laden und nach Filteränderung verwendet.
+
+## Ordnerstruktur
+```
+/
+├── index.html              # Einstiegspunkt der UI
+├── css/
+│   └── style.css           # Layout und visuelle Struktur
+├── js/
+│   ├── api.js              # Schnittstelle zu /api/retry-stats
+│   ├── charts.js           # Modul zur Diagramm-Visualisierung
+│   ├── filters.js          # Filterlogik für Stratum / Policy
+│   └── app.js              # Einstiegspunkt der internen Logik
+├── README.md               # (diese Datei)
+└── ...                     # Weitere unterstützende Dateien
+```
+
+## Nutzungshinweise
+- Öffne `index.html` in einem Browser mit Zugriff auf die definierte API.
+- Stelle sicher, dass der API-Endpunkt `/api/retry-stats` erreichbar ist.
+- Wähle über die Filterleiste gewünschte Stratums oder Policy-IDs, um die Datenansicht zu fokussieren.
+- Änderungen werden sofort reflektiert, ein Neuladen der Seite ist nicht erforderlich.
+
+## Entwicklung & Erweiterung
+- Neue Metriken können über die JSON-Antwort integriert und in `charts.js` visualisiert werden.
+- Styles sind komponentenbasiert und folgen dem BEM-Prinzip.
+- Die Anwendung ist so ausgelegt, dass Erweiterungen für weitere Run-Analysen (z. B. Run #18) einfach möglich sind.
+
+---
+
+© 2026 Donau2Space.de