Add visualization_tool/README.md

visualization_tool/README.md

@@ -0,0 +1,101 @@
+# Laufzeit-Analyse- und Visualisierungs-Tool
+
+## Ziel der Anwendung
+Dieses Web-Tool dient der **Analyse und Visualisierung von Laufzeitdaten** unterschiedlicher Runs. Es ermöglicht eine präzisere Bewertung von Timing-Entscheidungen durch interaktive Diagramme, eine klare 2×2‑Matrix-Darstellung sowie flexible Filtermöglichkeiten. 
+
+---
+
+## Hauptfunktionen
+- **Visualisierung von Δt‑Verteilungen:** Darstellung der zeitlichen Differenzen zwischen Runs als Histogramm oder Scatterplot.
+- **Analyse-Matrix (2×2):** Übersichtliche Zuordnung von Fällen nach *pinned / unpinned* und *Δt ≥ 0 / Δt < 0*.
+- **Filter:** Auswahl bestimmter Runs per `policy_hash` oder `Run‑Nummer`.
+- **Interaktive Charts:** Darstellung von Trends und Metriken (z. B. Warn‑ und Unknown‑Rate) mit Live‑Updates.
+- **API‑gestützte Datenerfassung:** Automatischer Abruf aggregierter Laufdaten über `/api/data`.
+- **Responsives Dashboard:** Anpassungsfähiges Layout für Desktop und Mobile.
+- **Analyse‑Zusammenfassung:** Kompakte Darstellung der wichtigsten Erkenntnisse aus dem aktuellen Datensatz.
+
+---
+
+## Architektur & Aufbau
+
+Die Anwendung besteht aus drei zentralen Bestandteilen:
+
+### 1. **HTML (Basisgerüst)**
+Strukturiert das Dashboard mit Komponenten wie Filter‑Bereich, Matrix‑Viewer, Chart‑Container und Analyse‑Summary.
+
+### 2. **CSS (Layout & Design)**
+Verwaltet das responsive Erscheinungsbild auf Basis eines flexiblen Grid‑Layouts. 
+CSS‑Variablen steuern Farben, Abstände und Schrifthöhen, um Einheitlichkeit über das gesamte Dashboard sicherzustellen.
+
+### 3. **JavaScript (Logik & Interaktivität)**
+Modularisiert in folgende Dateien:
+
+- `js/api.js` – Fetch‑Logik für die REST‑Route `/api/data`.
+- `js/dataLoader.js` – Berechnung und Aufbereitung der Metriken aus den API‑Daten.
+- `js/chartRenderer.js` – Visualisierung der vorbereiteten Daten in interaktiven Diagrammen.
+- `js/app.js` – Einstiegspunkt; regelt Datenfluss, Initialisierung und Benutzerinteraktion.
+
+---
+
+## Datenfluss & API‑Nutzung
+
+Die Datenpipeline folgt einem klaren Ablauf:
+
+1. **Abruf:** `app.js` ruft mit `fetch` die Daten von `/api/data` ab.
+2. **Verarbeitung:** `dataLoader` bereitet die Daten auf, berechnet Kennzahlen und verteilt sie an die Visualisierungs‑Module.
+3. **Darstellung:** `chartRenderer` aktualisiert dynamisch die Diagramme und Matrices im Dashboard.
+
+### API‑Route `/api/data`
+**Methode:** `GET`
+
+**Parameter (optional):**
+- `run`
+- `policy_hash`
+- `filter_pinned`
+
+**Antwortstruktur:** JSON‑Array von Objekten mit:
+```json
+{
+  "run_id": 42,
+  "policy_hash": "abc123",
+  "pinned_status": true,
+  "delta_t": -0.12,
+  "warn_rate": 0.04,
+  "unknown_rate": 0.01
+}
+```
+
+Diese Daten dienen der Erzeugung der Δt‑Verteilung und der statistischen Auswertung in der 2×2‑Matrix.
+
+---
+
+## Nutzung & Bedienung
+
+1. **Start:** Öffnen der Hauptseite im Browser.
+2. **Filter setzen:** Auswahl nach gewünschtem Run oder Policy‑Hash.
+3. **Analyse starten:** Die Charts und die Matrix aktualisieren sich automatisch.
+4. **Ergebnisse interpretieren:** Dashboard‑Summary zeigt zentral aggregierte Kennzahlen.
+
+Das Tool arbeitet vollständig client‑seitig und ruft Daten ausschließlich über die definierte API ab.
+
+---
+
+## Responsives Verhalten
+
+Das Dashboard verwendet ein flexibles Layout, das sich an Bildschirmbreiten anpasst:
+- **Mobile:** vertikal gestapelte Module.
+- **Desktop:** nebeneinanderliegende Analysebereiche mit skalierenden Diagrammen.
+
+---
+
+## Erweiterungshinweise
+
+- Neue Metriken können in `dataLoader.js` berechnet und direkt an `chartRenderer` übergeben werden.
+- Zusätzliche Filteroptionen können im HTML‑Filterbereich ergänzt werden; die Event‑Verarbeitung erfolgt zentral über `app.js`.
+- Weitere API‑Routen lassen sich analog zu `/api/data` integrieren, solange sie JSON liefern.
+
+---
+
+## Lizenz & Copyright
+
+© 2026 Donau2Space.de