From e2429fa085098c581e3043f3466f544bffea6d57 Mon Sep 17 00:00:00 2001
From: Mika <kontakt@donau2space.de>
Date: Fri, 23 Jan 2026 12:53:30 +0000
Subject: [PATCH] Add README.md

---
 README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8221b4b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+# Birthday Experiment Runs
+
+## Überblick
+Dieses Repository dokumentiert das Projekt **birthday_experiment_runs**. Es handelt sich um ein experimentelles System zur Analyse von Run-Daten in Bezug auf „pinned“ und „unpinned“ Ausführung. Ziel ist die Untersuchung der Auswirkungen auf Performance und Stabilität anhand von Mess- und Vergleichsdaten, die automatisiert ausgewertet und visualisiert werden.
+
+**Link zum Artikel:** [https://donau2space.de/tag-127-1346-geburtstag-bedecktes-passau-und-sechs-neue-runs-ohne-ausreden/](https://donau2space.de/tag-127-1346-geburtstag-bedecktes-passau-und-sechs-neue-runs-ohne-ausreden/)
+
+**Git Repository:** [https://git.donau2space.de/Mika/birthday_experiment_runs](https://git.donau2space.de/Mika/birthday_experiment_runs)
+
+## Hinweis
+Alle Inhalte wurden per KI generiert.
+
+Nutzung, Anpassung und Weiterentwicklung erfolgen eigenverantwortlich auf eigenes Risiko. Es wird keine Korrektheit, Sicherheit, Funktionsfähigkeit oder rechtliche Eignung zugesichert.
+
+## Inhalt des Repositories
+
+### 1. sanity_check_tool
+**Art:** Python Script  
+**Ziel:** Linux-Demo  
+**Sprachen:** Python  
+**Zweck:** Führt Sanity-Checks auf den Run-Daten durch, um strukturelle und datenbezogene Anomalien zu identifizieren.
+
+**API-Funktionen:**
+- **perform_sanity_checks(run_data)** → Gibt eine JSON-Struktur *check_results* zurück, die Informationen über fehlende, fehlerhafte oder leere Felder enthält.
+
+**Datenstrukturen:**
+- *run_data (JSON):* runs, sanity_checks
+- *check_results (JSON):* missing_pairs, broken_ids, empty_fields, clock_switch_count
+
+---
+
+### 2. experiment_results_visualization
+**Art:** Web UI  
+**Ziel:** Web  
+**Sprachen:** HTML, CSS, JavaScript  
+**Zweck:** Visualisiert und vergleicht Experimentresultate zwischen pinned und unpinned Runs.
+
+**API-Funktionen:**
+- **fetch_results()** → Gibt *experiment_data* zurück, die pinned/unpinned Ergebnisse enthält.
+
+**Routen:**
+- **GET /results:** Lädt die aktuellen Versuchsergebnisse.
+
+**Datenstrukturen:**
+- *experiment_data (JSON):* pinned, unpinned
+
+---
+
+### 3. data_export
+**Art:** CSV Dataset  
+**Ziel:** Mixed  
+**Sprachen:** CSV  
+**Zweck:** Exportiert die aggregierten Messdaten als CSV-Datei, um externe Analysen zu ermöglichen.
+
+**API-Funktionen:**
+- **export_data(experiment_data)** → Erzeugt eine CSV-Datei für Weiterverarbeitung.
+
+**Datenstrukturen:**
+- *experiment_data (CSV):* run_id, pinned_duration, unpinned_duration, latency
+
+
+## Voraussetzungen (Webserver/DB)
+Für das Web-Frontend wird ein Standard-Webserver (z. B. NGINX oder Apache) empfohlen. Es ist keine Datenbank zwingend erforderlich; experiment_data kann lokal als JSON-Datei bereitgestellt werden.
+
+
+## Installation & Nutzung
+1. **Python-Komponente (sanity_check_tool):**
+   - Voraussetzung: Python ≥ 3.8
+   - Installation der Abhängigkeiten: `pip install -r requirements.txt`
+   - Ausführung: `python sanity_check_tool.py`
+
+2. **Web-Frontend (experiment_results_visualization):**
+   - Dateien in ein Webserver-Verzeichnis legen
+   - Im Browser öffnen: `http://localhost/results`
+
+3. **CSV-Datenexport:**
+   - Das Skript erzeugt exportierte CSV-Dateien zur Weiterverwendung.
+
+
+## Typische Use-Cases
+- Überprüfung der Datenqualität vor weiteren Analysen.
+- Visualisierung von Performance-Unterschieden zwischen pinned und unpinned Runs.
+- Export der Ergebnisdaten für statistische oder externe Tools.
+
+
+## Struktur & mögliche Erweiterungen
+- **/scripts/** enthält Python-Tools für Analysen und Sanity-Checks.
+- **/web/** enthält das Web-Frontend für Visualisierung.
+- **/data/** enthält CSV-Exporte und Eingabedaten.
+
+Mögliche Erweiterungen:
+- Automatisierte Auswertung über zusätzliche Python-Module.
+- Integration weiterer Visualisierungskomponenten (z. B. D3.js).
+
+
+## Lizenz
+Dieses Projekt steht unter der **MIT-Lizenz**.  
+Die Nutzung erfolgt auf eigene Verantwortung.
\ No newline at end of file