# Retrospektive — Epic 3: Visueller Baukasten Frontend (Phase 2)

<!-- 🏃 Facilitiert von BMAD SM Skill — Agent: Bob (Scrum Master) -->
<!-- Skill Command: /bmad-agent-bmm-sm → [ER] Epic Retrospective -->
<!-- Workflow: _bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml -->

**Datum:** 2026-03-12
**Epic:** Epic 3 — Visueller Baukasten Frontend (Phase 2)
**Status:** Abgeschlossen — 4/4 Stories erledigt
**Facilitiert von:** Bob (🏃 Scrum Master)

---

## 1. Epic-Zusammenfassung

**Ziel:** React Flow Canvas mit Custom Nodes/Edges, Node-Einstellungs-Panel, Blueprint-Parser und PostgreSQL-Speicherung.

**Stories abgeschlossen:**
- ✅ 3.1: React-Flow-Canvas mit Custom Agent Node
- ✅ 3.2: Lineare und bedingte Edges
- ✅ 3.3: Blueprint-Parser (React Flow → JSON)
- ✅ 3.4: Blueprint CRUD — Frontend & Backend

---

## 2. Was lief gut? (Keep)

**Technische Entscheidungen:**
- **Zustand (Zustand-Store)** erwies sich als ideale Wahl für Canvas-State-Management — einfacher als Redux, aber mächtig genug für Node/Edge-Verwaltung
- **React Flow `@xyflow/react`** lieferte out-of-the-box Handle-System und Drag & Drop — deutlich weniger Eigenimplementierung als erwartet
- **Blueprint-Parser** (`parseGraphToBlueprint`) sauber als reine Funktion implementiert — einfach zu testen und leicht zu erweitern
- **Trennung API-Client / Store / Parser** hält die Frontend-Architektur wartbar

**Prozess:**
- Story 3.3 (Blueprint-Parser) wurde zuerst fertiggestellt und als Basis für Story 3.4 verwendet — richtige Reihenfolge
- Vitest-Tests für den Parser und Store gaben schnelles Feedback ohne Browser-Start
- Service-Layer im Backend (`blueprint_service.py`) macht API-Tests unabhängig von HTTP-Details

---

## 3. Was lief nicht gut? (Drop / Improve)

**Technisch:**
- `@xyflow/react` SSR-Kompatibilität mit Next.js erforderte `"use client"`-Direktive in allen Canvas-Komponenten — muss beim Hinzufügen neuer Komponenten immer bedacht werden
- Die Typ-Kette (`AgentNodeData` → `BlueprintNode` → Backend-Schema) führte bei Änderungen zu Kaskaden-Updates in mehreren Dateien
- `EdgeSettingsPanel` fehlt noch eine Bestätigungs-UX wenn die Edge-Bedingung geändert wird

**Prozess:**
- Blueprint-CRUD-Tests hätten früher geschrieben werden können — TDD wäre hier effizienter gewesen
- Edge-Typ-Logik (linear vs. conditional) war in mehreren Dateien verteilt — ein zentrales `edge-utils.ts` wäre klarer

---

## 4. Lernerkenntnisse

| Erkenntnis | Anwendung in kommenden Epics |
|------------|------------------------------|
| React Flow Custom Nodes/Edges brauchen explizite Registrierung in `nodeTypes`/`edgeTypes` | Für Live-Canvas in Epic 4 dieselbe Registrierung wiederverwenden |
| JSONB in PostgreSQL erlaubt Schema-freie Blueprint-Evolution | Version-Feld im Blueprint nutzen bevor Phase 4 neue Felder hinzufügt |
| Zustand-Selektoren minimieren Re-Renders | Für Konferenzzimmer-State (Epic 4) denselben Store erweitern |
| `parseGraphToBlueprint` ist idempotent | Kann für Auto-Save-Feature bedenkenlos mehrfach aufgerufen werden |

---

## 5. Aktionspunkte für kommende Epics

| Priorität | Aktionspunkt | Verantwortlich | Status |
|-----------|-------------|----------------|--------|
| Hoch | Live-Canvas in Epic 4 als read-only Variante von `ArchitectCanvas` realisieren — gleiche Node-Typen, aber `nodesDraggable={false}` | Dev | Umgesetzt in Story 4.3 |
| Mittel | Edge-Utility-Funktionen in `utils/edge-utils.ts` zentralisieren | Dev | Backlog |
| Mittel | `"use client"`-Direktiven-Check in ESLint-Regel aufnehmen | Dev | Backlog |

---

## 6. Nächstes Epic (Preview: Epic 4)

**Epic 4 — Frontend-Backend-Integration** baut direkt auf dem Blueprint-Format aus Epic 3 auf:
- Der dynamische Graph-Builder liest das JSON-Blueprint (Story 4.1 ✅)
- WebSocket-Events pulsieren Nodes im Live-Canvas (Story 4.2 ✅)
- Das Konferenzzimmer zeigt den laufenden Council (Story 4.3 ✅)

**Wichtige Brücke:** Blueprint-JSON aus Epic 3 ist das kanonische Austauschformat zwischen Frontend und Backend — Versionsnummer muss vor Phase-4-Änderungen inkrementiert werden.

---

*Bob (Scrum Master): "Epic 3 hat die visuelle Grundlage gelegt. Alle funktionalen Requirements FR-01.1–01.7 und FR-06.1–06.3 sind erfüllt. Der Blueprint-Parser als reine Funktion ist ein echter Gewinn für die Testbarkeit. Gut gemacht, Team!"*