diff --git a/heatmap_visualization/README.md b/heatmap_visualization/README.md
new file mode 100644
index 0000000..049a2c8
--- /dev/null
+++ b/heatmap_visualization/README.md
@@ -0,0 +1,73 @@
+# Heatmap Visualization – Resonanzband Untersuchung
+
+## Ziel
+Diese Komponente stellt eine interaktive **Heatmap** zur Visualisierung von Resonanzband-Daten bereit. Ziel ist die Analyse der Band-Lage und Dynamik innerhalb experimenteller Startkohorten. Nutzer können Zeitfenster und Kohorten filtern, um Veränderungen in Bandposition und Intensität zu untersuchen.
+
+## Hauptfunktionen
+- **Interaktive Heatmap:** Darstellung der Resonanzband-Verteilung mit skalierbarer Farbpalette.
+- **Dynamische Datenanbindung:** Abruf der Heatmap-Daten über die API `/heatmap` (GET).
+- **Filtersteuerung:** Auswahl von Kohorte und Zeitfenster zur gezielten Analyse.
+- **Metriken:** Anzeige zusätzlicher Werte wie `band_center`, `band_width` und `cluster_score`.
+- **Tooltip-Interaktion:** Detailinformationen pro Heatmap-Zelle durch Hover-Aktion.
+- **Responsive Darstellung:** Anpassung für verschiedene Bildschirmgrößen.
+
+## Datenflussübersicht
+1. Beim Laden der Seite wird ein GET-Request an `/heatmap` gesendet.
+2. Die API liefert ein JSON-Objekt:
+   ```json
+   {
+     "matrix": [ [0.3, 0.5, ...], [0.6, 0.8, ...] ],
+     "band_center": 125.4,
+     "band_width": 12.7,
+     "cluster_score": 0.89
+   }
+   ```
+3. Die Daten werden im Browser verarbeitet und per Canvas oder SVG visualisiert.
+4. Änderungen an Filtern lösen ein erneutes Datenladen und Re-Rendering aus.
+
+## API-Nutzung
+**Route:** `/heatmap`
+
+**Methode:** `GET`
+
+**Optionale Parameter:**
+- `cohort_id`: ID der Kohorte, deren Daten geladen werden sollen
+- `time_window`: Zeitbereich zur Beschränkung der Darstellung
+
+**Response-Format:** JSON-Objekt mit Heatmap-Matrix und Metadaten:
+```json
+{
+  "matrix": number[][],
+  "band_center": number,
+  "band_width": number,
+  "cluster_score": number
+}
+```
+
+**Verwendung in Dateien:**
+- `js/api.js`: Abfrage der Daten über Fetch.
+- `js/app.js`: Verarbeitung, Rendering und Benutzerinteraktion.
+
+## Dateistruktur
+```
+│
+├─ js/
+│  ├─ api.js        # Schnittstellenaufrufe zur Heatmap-API
+│  └─ app.js        # Hauptlogik und Eventsteuerung
+│
+├─ css/
+│  └─ styles.css    # Layout, Farbskala, Tooltip-Stile
+│
+├─ index.html       # Einstiegspunkt der Anwendung
+└─ README.md        # Projektdokumentation
+```
+
+## Entwicklungshinweise
+- Mobile-First CSS-Ansatz
+- Verwendung semantischer HTML-Struktur (main, section, header, footer)
+- Keine externen Assets oder Fonts
+- Nutzung moderner ES6+ Features (const/let, async/await, Template Literals)
+- Alle API-Aufrufe erfolgen asynchron mit Fehlerhandling
+
+## Lizenz & Copyright
+© 2026 Donau2Space.de