Add BMAD planning artifacts: PRD, Architecture, UX Design (pre-skill attribution)

Co-authored-by: Kenearos <86194771+Kenearos@users.noreply.github.com>

_bmad-output/planning-artifacts/architecture.md

@@ -0,0 +1,424 @@
+---
+stepsCompleted:
+  - step-01-init
+  - step-02-context
+  - step-03-starter
+  - step-04-decisions
+  - step-05-patterns
+  - step-06-structure
+  - step-07-validation
+  - step-08-complete
+inputDocuments:
+  - _bmad-output/planning-artifacts/prd.md
+  - CLAUDE.md
+  - README.md
+---
+
+# Architektur-Entscheidungsdokument — CouncilOS
+
+**Autor:** KI-Konzil Dev-Team
+**Datum:** 2026-03-12
+**Version:** 1.0.0
+**Bezug:** PRD v1.0.0
+
+---
+
+## 1. Architektur-Überblick
+
+CouncilOS ist eine Full-Stack-Webanwendung bestehend aus einem **FastAPI-Backend** (Python), einem **Next.js-Frontend** (TypeScript) und einer **PostgreSQL-Datenbank**. Die Kernintelligenz liegt im **LangGraph-Engine**, der zyklische Multi-Agenten-Graphen ausführt.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Browser (Next.js)                       │
+│  ┌─────────────────────┐    ┌──────────────────────────────┐   │
+│  │  Rat-Architekt Tab  │    │   Konferenzzimmer Tab        │   │
+│  │  (React Flow Canvas)│    │   (Execution View)            │   │
+│  └─────────────────────┘    └──────────────────────────────┘   │
+└─────────────┬───────────────────────────┬───────────────────────┘
+              │ REST (HTTP/JSON)           │ WebSocket
+              ▼                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      FastAPI Backend                            │
+│  ┌──────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
+│  │  REST Routes │  │  WebSocket Route │  │  Background Tasks│  │
+│  └──────────────┘  └──────────────────┘  └──────────────────┘  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                    LangGraph Engine                      │   │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │   │
+│  │  │ Master Agent│  │ Critic Agent│  │  Writer Agent   │  │   │
+│  │  └──────┬──────┘  └──────┬──────┘  └────────┬────────┘  │   │
+│  │         └────────────────┼──────────────────┘           │   │
+│  │              CouncilState (TypedDict)                    │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└──────────────────────┬──────────────────────────────────────────┘
+                       │
+         ┌─────────────┼─────────────┐
+         ▼             ▼             ▼
+    PostgreSQL      ChromaDB      LLM APIs
+    (Blueprints)  (PDF-Vektor)  (Anthropic/OpenAI)
+```
+
+---
+
+## 2. Architektur-Entscheidungen (ADRs)
+
+### ADR-001: LangGraph als KI-Orchestrierungs-Framework
+
+**Kontext:** Wir benötigen ein Framework, das echte Zyklen (Loops) in KI-Agenten-Pipelines unterstützt und Human-in-the-Loop ermöglicht.
+
+**Entscheidung:** LangGraph (Python) wird als einziges KI-Orchestrierungs-Framework verwendet.
+
+**Begründung:**
+- LangGraph unterstützt native Zyklen (A → B → A) ohne Workarounds.
+- `interrupt_before` für Human-in-the-Loop ist eingebaut.
+- `CouncilState` als TypedDict mit `operator.add`-Reducern für sichere State-Akkumulation.
+- Andere Frameworks (LangChain, AutoGen) unterstützen keine echten Zyklen.
+
+**Konsequenzen:** LangGraph-Versionen ≥ 0.2.x sind Voraussetzung. Synchrone `graph.invoke()`-Aufrufe werden in Thread-Pools ausgeführt, um den FastAPI-Event-Loop nicht zu blockieren.
+
+---
+
+### ADR-002: FastAPI mit asyncio + Background Tasks
+
+**Kontext:** LangGraph-Runs können mehrere Minuten dauern und müssen nicht-blockierend ausgeführt werden.
+
+**Entscheidung:** FastAPI mit `BackgroundTasks` + `asyncio.get_event_loop().run_in_executor()` für alle LangGraph-Aufrufe.
+
+**Begründung:**
+- Background Tasks ermöglichen sofortige HTTP-Antwort (202 Accepted) mit `run_id`.
+- `run_in_executor()` verhindert Blockierung des Event Loops durch synchrones LangGraph.
+- Clients können per WebSocket live-Updates empfangen oder per GET pollen.
+
+**Konsequenzen:** Run-Status wird in einem In-Memory-Store (`run_store`) zwischen Tasks geteilt. Bei Neustart des Servers gehen laufende Runs verloren — akzeptabel für MVP.
+
+---
+
+### ADR-003: WebSocket für Echtzeit-Agent-Events
+
+**Kontext:** Das Frontend muss in Echtzeit wissen, welcher Agent gerade arbeitet, damit der Node im Canvas pulsiert.
+
+**Entscheidung:** Dedizierter WebSocket-Endpoint `/ws/council/{run_id}` pro Council-Run.
+
+**Begründung:**
+- Polling ist nicht akzeptabel (zu hohe Latenz, unnötige Serverlast).
+- WebSockets ermöglichen Push-Events innerhalb von 500 ms.
+- Jede `run_id` hat eine eigene isolierte WebSocket-Session — kein Event-Crossover.
+
+**Konsequenzen:** WebSocket-Sessions werden in einem `connection_manager` verwaltet. Verbindungsabbrüche müssen graceful behandelt werden.
+
+---
+
+### ADR-004: Dynamischer Graph-Builder (Phase 3)
+
+**Kontext:** Ab Phase 3 muss der LangGraph-Graph aus einem JSON-Blueprint dynamisch aufgebaut werden.
+
+**Entscheidung:** `dynamic_graph_builder.py` interpretiert das Blueprint-JSON und konstruiert den `StateGraph` zur Laufzeit.
+
+**Begründung:**
+- Hartcodierte Graphen in Produktion verstoßen gegen die Kern-Design-Constraint.
+- Das Blueprint-JSON ist das kanonische Austauschformat zwischen Frontend und Backend.
+- Zyklen müssen im JSON darstellbar sein und dürfen nicht zu DAGs vereinfacht werden.
+
+**Konsequenzen:** Blueprint-JSON muss versioniert sein (`version`-Feld). Ungültige Blueprints müssen mit klaren Fehlermeldungen abgelehnt werden.
+
+---
+
+### ADR-005: PostgreSQL + JSONB für Blueprints
+
+**Kontext:** Blueprint-Konfigurationen sind komplexe, verschachtelte Objekte, die sich über die Zeit ändern.
+
+**Entscheidung:** PostgreSQL 16 mit JSONB-Spalte für Blueprint-Daten.
+
+**Begründung:**
+- JSONB ermöglicht flexible Schema-Entwicklung ohne Migrationszwang bei jedem neuen Feld.
+- PostgreSQL ist für alle anderen relationalen Daten (Council-Run-Verlauf) bereits vorhanden.
+- Ein `version`-Feld im JSONB ermöglicht Schema-Versionierung.
+
+**Konsequenzen:** Alembic verwaltet Datenbankmigrationen. SQLAlchemy (async) wird als ORM verwendet.
+
+---
+
+### ADR-006: ChromaDB für PDF-Vektor-Suche
+
+**Kontext:** Agents müssen auf Inhalte aus hochgeladenen PDFs zugreifen können.
+
+**Entscheidung:** ChromaDB (lokal, persistent) als Vektor-Datenbank.
+
+**Begründung:**
+- Kostenlos, lokal betreibbar, keine externe API.
+- `PersistentClient` überlebt Server-Neustarts.
+- Cosine-Similarity für semantische Suche eingebaut.
+
+**Konsequenzen:** `CHROMA_PERSIST_DIR` Umgebungsvariable muss gesetzt sein. In Docker Compose wird ein Named Volume verwendet.
+
+---
+
+## 3. Datenmodell
+
+### 3.1 CouncilState (TypedDict)
+
+```python
+class CouncilState(TypedDict):
+    input_topic: str          # Ursprungsthema / PDF-Inhalt des Nutzers
+    current_draft: str        # Das aktuell bearbeitete Dokument
+    feedback_history: Annotated[List[str], operator.add]  # Akkumuliertes Kritiker-Feedback (append-only)
+    route_decision: str       # Routing-Signal: "rework" | "approve" | benutzerdefiniert
+    messages: Annotated[list, operator.add]  # LLM-Nachrichtenverlauf (akkumulierend)
+    iteration_count: int      # Anzahl Rework-Schleifen
+    critic_score: Optional[float]  # Numerische Bewertung (0–10)
+    run_id: str               # Eindeutige Run-ID (für WebSocket-Events)
+    active_node: str          # Name des aktuell aktiven Agent-Nodes
+```
+
+**Wichtig:** `feedback_history` und `messages` verwenden `operator.add` als Reducer — sie werden niemals überschrieben, nur angehängt.
+
+### 3.2 Blueprint-JSON-Schema
+
+```json
+{
+  "version": "1.0",
+  "name": "Mein Content-Rat",
+  "nodes": [
+    {
+      "id": "node-1",
+      "type": "agent",
+      "name": "Master KI",
+      "system_prompt": "Du bist ein erstklassiger Content-Writer...",
+      "model": "claude-3-5-sonnet-20241022",
+      "tools": {
+        "web_search": false,
+        "pdf_reader": false
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "edge-1",
+      "source": "node-1",
+      "target": "node-2",
+      "type": "linear"
+    },
+    {
+      "id": "edge-2",
+      "source": "node-2",
+      "target": "node-1",
+      "type": "conditional",
+      "condition": "rework"
+    }
+  ]
+}
+```
+
+### 3.3 Datenbankschema (PostgreSQL)
+
+**Tabelle `blueprints`:**
+
+| Spalte | Typ | Beschreibung |
+|--------|-----|--------------|
+| `id` | UUID | Primärschlüssel |
+| `name` | VARCHAR(255) | Name des Councils |
+| `data` | JSONB | Blueprint-JSON |
+| `created_at` | TIMESTAMP | Erstellungszeitpunkt |
+| `updated_at` | TIMESTAMP | Letzter Update |
+
+**Tabelle `council_runs`:**
+
+| Spalte | Typ | Beschreibung |
+|--------|-----|--------------|
+| `id` | UUID | Primärschlüssel |
+| `blueprint_id` | UUID | FK → `blueprints.id` (nullable für Phase-1-Runs) |
+| `input_topic` | TEXT | Eingabe-Prompt |
+| `status` | VARCHAR(50) | `pending`\|`running`\|`completed`\|`failed`\|`paused` |
+| `final_draft` | TEXT | Finaler Output |
+| `critic_score` | FLOAT | Letzte Critic-Bewertung |
+| `iteration_count` | INT | Anzahl Rework-Schleifen |
+| `created_at` | TIMESTAMP | Startzeitpunkt |
+| `completed_at` | TIMESTAMP | Endzeitpunkt |
+
+---
+
+## 4. Komponentenstruktur
+
+### 4.1 Backend-Verzeichnisstruktur
+
+```
+backend/
+├── main.py                  # FastAPI-Entrypoint
+├── state.py                 # CouncilState TypedDict + Konstanten
+├── database.py              # Async SQLAlchemy setup + Session
+├── alembic.ini              # Alembic-Konfiguration
+├── alembic/                 # Datenbankmigrationen
+│   └── versions/
+├── api/
+│   ├── routes.py            # Run-Endpunkte + Health-Check
+│   ├── blueprint_routes.py  # Blueprint-CRUD-Endpunkte
+│   ├── run_history_routes.py # Run-Verlauf-Endpunkte
+│   ├── run_store.py         # In-Memory-Run-Status-Store
+│   └── websocket.py         # WebSocket-Connection-Manager + Route
+├── agents/
+│   ├── master_agent.py      # Master-Agent-Node
+│   ├── critic_agent.py      # Critic-Agent-Node + Routing
+│   └── writer_agent.py      # Writer-Agent-Node
+├── services/
+│   ├── graph_builder.py     # Phase-1-Hartcodierter-Graph
+│   ├── dynamic_graph_builder.py  # Phase-3-Dynamischer-Graph aus Blueprint
+│   ├── blueprint_service.py # Blueprint-CRUD-Service
+│   └── run_service.py       # Run-History-Service
+├── models/
+│   ├── blueprint.py         # SQLAlchemy Blueprint-Modell
+│   └── council_run.py       # SQLAlchemy CouncilRun-Modell
+└── tools/
+    ├── web_search.py        # Tavily-Web-Suche-Wrapper
+    └── pdf_reader.py        # PyPDF + ChromaDB-Wrapper
+```
+
+### 4.2 Frontend-Verzeichnisstruktur
+
+```
+frontend/
+├── app/
+│   ├── layout.tsx           # Root-Layout + Navigation-Tabs
+│   ├── page.tsx             # Redirect → /rat-architekt
+│   ├── rat-architekt/       # Tab A: Visueller Canvas
+│   │   └── page.tsx
+│   ├── konferenzzimmer/     # Tab B: Ausführung
+│   │   └── page.tsx
+│   ├── components/
+│   │   ├── ArchitectCanvas.tsx   # React Flow Canvas
+│   │   ├── NavTabs.tsx           # Tab-Navigation
+│   │   ├── nodes/               # Custom React Flow Nodes
+│   │   ├── edges/               # Custom React Flow Edges
+│   │   └── panels/              # Sidebar + Settings-Panels
+│   ├── hooks/               # Custom React Hooks (WebSocket, API)
+│   ├── store/               # Zustand State Management
+│   ├── types/               # TypeScript-Typen
+│   └── utils/
+│       ├── blueprint-parser.ts  # React Flow → Blueprint JSON
+│       └── api-client.ts       # HTTP-Client für Backend-API
+└── __tests__/               # Vitest-Tests
+```
+
+---
+
+## 5. API-Vertragsübersicht
+
+### 5.1 REST-Endpunkte
+
+| Methode | Pfad | Beschreibung |
+|---------|------|--------------|
+| `POST` | `/api/councils/` | Blueprint erstellen |
+| `GET` | `/api/councils/` | Alle Blueprints auflisten |
+| `GET` | `/api/councils/{id}` | Einzelnen Blueprint abrufen |
+| `PUT` | `/api/councils/{id}` | Blueprint aktualisieren |
+| `DELETE` | `/api/councils/{id}` | Blueprint löschen |
+| `POST` | `/api/councils/run` | Phase-1-Run starten |
+| `POST` | `/api/councils/{id}/run` | Blueprint-Run starten |
+| `GET` | `/api/councils/run/{run_id}` | Run-Status/Ergebnis abrufen |
+| `POST` | `/api/councils/run/{run_id}/approve` | God Mode: genehmigen/ablehnen/modifizieren |
+| `GET` | `/api/councils/run/{run_id}/state` | God Mode: pausierten State abrufen |
+| `POST` | `/api/councils/upload-pdf` | PDF hochladen und in ChromaDB einlesen |
+| `GET` | `/api/runs/` | Run-Verlauf auflisten |
+| `GET` | `/api/runs/{run_id}` | Run-Verlauf-Detail |
+| `GET` | `/api/health` | Health-Check |
+
+### 5.2 WebSocket
+
+| Endpoint | Event-Format |
+|----------|--------------|
+| `WS /ws/council/{run_id}` | `{"node": "master_agent", "status": "running"}` |
+
+**Status-Werte:** `running` \| `completed` \| `done`
+
+---
+
+## 6. Sequenzdiagramm: Council-Run
+
+```
+Nutzer       Frontend        FastAPI         LangGraph        LLM API
+  │              │               │                │               │
+  ├─POST /run───►│               │                │               │
+  │              ├─POST /run────►│                │               │
+  │              │               ├─202 (run_id)──►│               │
+  │              │               ├─Background:─────────────────►  │
+  │              │               │ graph.invoke()  │               │
+  │              ├─WS connect───►│                │               │
+  │              │               │                │               │
+  │              │               │ [Node: master_agent running]    │
+  │              │               ├─WS event───────────────────────►
+  │              │◄─WS: running──┤                │               │
+  │              │               │                ├─LLM call──────►
+  │              │               │                │◄──response────┤
+  │              │               │ [Node: critic_agent running]    │
+  │              │◄─WS: running──┤                │               │
+  │              │               │                ├─LLM call──────►
+  │              │               │                │◄──response────┤
+  │              │               │ [score < 8 → rework]           │
+  │              │               │ [Node: master_agent running]    │
+  │              │◄─WS: running──┤                │               │
+  │              │               │                 ...            │
+  │              │               │ [score ≥ 8 → approve]          │
+  │              │               │ [Node: writer_agent running]   │
+  │              │◄─WS: running──┤                │               │
+  │              │               │                ├─LLM call──────►
+  │              │               │                │◄──response────┤
+  │              │◄─WS: done─────┤                │               │
+  ├─GET /result─►│               │                │               │
+  │              ├─GET result───►│                │               │
+  │              │◄──final draft─┤                │               │
+```
+
+---
+
+## 7. God Mode — Sequenzdiagramm
+
+```
+Nutzer       Frontend        FastAPI         LangGraph
+  │              │               │                │
+  ├─POST /run (god_mode=true)────►               │
+  │              │               ├─interrupt_before──────────────►
+  │              │               │◄──paused state─┤
+  │              │◄─WS: paused───┤                │
+  │              │               │                │
+  ├─Approve/Reject/Modify────────►               │
+  │              │               ├─resume──────────────────────►
+  │              │               │◄──next state───┤
+  │              │               │                │
+  │              │     (repeat per node if god_mode=true)       │
+```
+
+---
+
+## 8. Sicherheitsüberlegungen
+
+1. **API-Key-Management:** Alle Secrets ausschließlich in `.env`-Dateien (gitignored).
+2. **CORS:** In Produktion auf bekannte Origins beschränken.
+3. **PDF-Upload-Validierung:** Nur `.pdf`-Dateien akzeptieren, Größenlimit durchsetzen.
+4. **Input-Validierung:** Pydantic-Modelle für alle API-Inputs mit `min_length`/`max_length`.
+5. **SQL-Injection:** SQLAlchemy ORM verhindert Raw-SQL-Injection.
+6. **Infinite-Loop-Schutz:** `MAX_ITERATIONS = 5` — nach 5 Rework-Schleifen automatische Genehmigung.
+
+---
+
+## 9. Deployment-Architektur (Lokal)
+
+```yaml
+# docker-compose.yml (vereinfacht)
+services:
+  db:      # PostgreSQL 16
+  api:     # FastAPI + LangGraph (Port 8000)
+  frontend: # Next.js (Port 3000)
+  
+volumes:
+  postgres_data:
+  chroma_data:
+```
+
+**Umgebungsvariablen (.env):**
+
+```
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+TAVILY_API_KEY=
+DATABASE_URL=postgresql+asyncpg://user:password@db:5432/councilOS
+CHROMA_PERSIST_DIR=./chroma_db
+```

_bmad-output/planning-artifacts/prd.md

@@ -0,0 +1,272 @@
+---
+stepsCompleted:
+  - step-v-01-discovery
+  - step-v-02-structure
+  - step-v-03-goals
+  - step-v-04-requirements
+  - step-v-05-measurability-validation
+  - step-v-06-traceability-validation
+  - step-v-10-smart-validation
+  - step-v-11-holistic-quality-validation
+  - step-v-12-completeness-validation
+inputDocuments:
+  - README.md
+  - CLAUDE.md
+workflowType: 'prd'
+---
+
+# Product Requirements Document — CouncilOS (KI-Rat Baukasten)
+
+**Autor:** KI-Konzil Dev-Team
+**Datum:** 2026-03-12
+**Version:** 1.0.0
+**Status:** Genehmigt
+
+---
+
+## 1. Projekt-Überblick
+
+### 1.1 Problemstellung
+
+Aktuelle KI-Tools (wie ChatGPT) arbeiten linear. Wenn ein Nutzer ein komplexes Ergebnis will — z. B. einen perfekten Blogartikel, rechtssichere PR-Texte oder lauffähigen Code — muss er den Output ständig manuell lesen, Fehler finden und die KI in endlosen Chat-Verläufen korrigieren. Das kostet Zeit und erfordert extrem gutes „Prompting".
+
+### 1.2 Lösung
+
+**CouncilOS** ist eine visuelle No-Code-Plattform. Anstatt selbst mit der KI zu chatten, baut der Nutzer sich einen eigenen **„KI-Rat" (Multi-Agenten-System)**. Der Nutzer definiert verschiedene KI-Experten, gibt ihnen Werkzeuge (Internet, PDF-Reader) und legt per Drag & Drop fest, in welcher Reihenfolge sie Dokumente bearbeiten, kritisieren und überarbeiten.
+
+### 1.3 Alleinstellungsmerkmal (USP)
+
+Im Gegensatz zu bestehenden Tools arbeiten die KIs in **Endlosschleifen (Zyklen)**. Eine Kritiker-KI kann ein Dokument so lange an die Master-KI zurückweisen, bis es perfekt ist, ohne dass der Mensch eingreifen muss. Wahlweise kann der Mensch als „Vorsitzender des Rates" jeden Schritt abnicken (God-Mode / Human-in-the-Loop).
+
+---
+
+## 2. Ziele und Erfolgsmetriken
+
+### 2.1 Geschäftsziele
+
+| Ziel | Messgröße | Zielwert |
+|------|-----------|---------- |
+| Nutzer können komplexe KI-Pipelines ohne Code aufbauen | Anzahl erfolgreich abgeschlossener Council-Runs | ≥ 100 Runs/Woche (Phase 3 Launch) |
+| Qualitätsverbesserung durch iterative Schleifen | Durchschnittlicher Critic-Score bei Abschluss | ≥ 8/10 |
+| Transparente KI-Nutzung | Anteil der Nutzer, die God-Mode verwenden | ≥ 20 % aller Runs |
+
+### 2.2 Nutzerziele
+
+- Nutzer können in < 5 Minuten einen KI-Rat aus Standard-Agents zusammenstellen und ausführen.
+- Nutzer sehen in Echtzeit, welcher Agent gerade arbeitet.
+- Im God Mode können Nutzer an jedem Entscheidungspunkt eingreifen.
+
+### 2.3 Technische Ziele
+
+- Backend-Latenz für einen einzelnen Agent-Node < 30 Sekunden (bei normalen LLM-Antwortzeiten).
+- WebSocket-Events werden innerhalb von 500 ms nach Node-Eintritt gesendet.
+- Das System unterstützt bis zu 10 gleichzeitige Council-Runs.
+
+---
+
+## 3. Zielgruppen
+
+### 3.1 Primäre Nutzer
+
+**Content-Ersteller und Marketing-Teams**
+- Erstellen Rohtexte, die von KI-Experten (SEO, Faktenprüfung, Lektor) in Schleifen verfeinert werden.
+- Technisches Know-how: gering bis mittel.
+- Kernbedürfnis: Qualitätssteigerung ohne manuelles Nacharbeiten.
+
+**Software-Entwickler und Architekten**
+- Lassen Code durch Architekten-KI, Tester-KI und Doku-KI überprüfen.
+- Technisches Know-how: hoch.
+- Kernbedürfnis: Automatisierte Code-Review-Schleifen.
+
+### 3.2 Sekundäre Nutzer
+
+**Analysten und Researcher**
+- Lassen 100-seitige PDFs durch KI-Ketten zusammenfassen und analysieren.
+- Kernbedürfnis: Informationsextraktion aus langen Dokumenten.
+
+---
+
+## 4. Funktionale Anforderungen
+
+### FR-01: Visueller Canvas (Rat-Architekt)
+
+| ID | Anforderung | Priorität |
+|----|-------------|-----------|
+| FR-01.1 | Der Nutzer kann Agent-Nodes per Drag & Drop auf den Canvas ziehen. | MUSS |
+| FR-01.2 | Ein Klick auf einen Node öffnet ein Einstellungs-Panel (Name, System-Prompt, LLM-Modell, Tools). | MUSS |
+| FR-01.3 | Der Nutzer kann lineare Edges (Pfeile) zwischen Nodes ziehen. | MUSS |
+| FR-01.4 | Der Nutzer kann bedingte Edges erstellen (mit Routing-Label). | MUSS |
+| FR-01.5 | Der Nutzer kann den Council unter einem Namen speichern. | MUSS |
+| FR-01.6 | Der Nutzer kann einen gespeicherten Council laden und bearbeiten. | SOLL |
+| FR-01.7 | Der Canvas unterstützt Export des Blueprints als JSON-Datei. | SOLL |
+
+### FR-02: Council-Ausführung (Konferenzzimmer)
+
+| ID | Anforderung | Priorität |
+|----|-------------|-----------|
+| FR-02.1 | Der Nutzer kann einen Prompt-Text als Eingabe für den Council angeben. | MUSS |
+| FR-02.2 | Der Nutzer kann ein PDF hochladen, dessen Inhalt als Eingabe dient. | SOLL |
+| FR-02.3 | Der Nutzer kann zwischen Auto-Pilot und God Mode wählen. | MUSS |
+| FR-02.4 | Im Auto-Pilot läuft der Council autonom bis zum Abschluss. | MUSS |
+| FR-02.5 | Im God Mode pausiert der Council vor jedem Agent und wartet auf Genehmigung. | MUSS |
+| FR-02.6 | Der Nutzer sieht das fertige Dokument nach Abschluss des Councils. | MUSS |
+| FR-02.7 | Der Nutzer kann vergangene Council-Runs in einem Verlauf einsehen. | SOLL |
+
+### FR-03: Echtzeit-Updates (WebSocket)
+
+| ID | Anforderung | Priorität |
+|----|-------------|-----------|
+| FR-03.1 | Der aktive Agent-Node leuchtet/pulsiert im Canvas (live). | MUSS |
+| FR-03.2 | WebSocket-Events enthalten: `node_name`, `status` (`running`/`completed`/`done`). | MUSS |
+| FR-03.3 | Bei Abschluss eines Runs wird ein `done`-Event gesendet. | MUSS |
+
+### FR-04: God Mode / Human-in-the-Loop
+
+| ID | Anforderung | Priorität |
+|----|-------------|-----------|
+| FR-04.1 | Im God Mode erscheint ein Popup mit dem Agent-Namen, Grund und Approve/Reject/Modify-Buttons. | MUSS |
+| FR-04.2 | „Approve" setzt die Ausführung am nächsten Node fort. | MUSS |
+| FR-04.3 | „Reject" bricht den Run ab und markiert ihn als fehlgeschlagen. | MUSS |
+| FR-04.4 | „Modify" erlaubt die Bearbeitung des aktuellen Drafts vor Fortsetzung. | SOLL |
+
+### FR-05: Agent-Konfiguration
+
+| ID | Anforderung | Priorität |
+|----|-------------|-----------|
+| FR-05.1 | Jeder Agent kann ein individuelles LLM-Modell zugewiesen bekommen (Claude 3.5 Sonnet, GPT-4o, lokal). | MUSS |
+| FR-05.2 | Jeder Agent kann optional Web-Suche aktiviert bekommen (Tavily). | SOLL |
+| FR-05.3 | Jeder Agent kann optional PDF-Reader aktiviert bekommen (ChromaDB). | SOLL |
+| FR-05.4 | Agent-Konfigurationen können gespeichert und wiederverwendet werden. | SOLL |
+
+### FR-06: Blueprint-Verwaltung (CRUD)
+
+| ID | Anforderung | Priorität |
+|----|-------------|-----------|
+| FR-06.1 | Blueprints können erstellt, gelesen, aktualisiert und gelöscht werden (REST API). | MUSS |
+| FR-06.2 | Blueprints werden in PostgreSQL als JSONB gespeichert. | MUSS |
+| FR-06.3 | Jeder Blueprint hat ein `version`-Feld. | MUSS |
+
+---
+
+## 5. Nicht-funktionale Anforderungen
+
+### NFR-01: Performance
+
+| ID | Anforderung |
+|----|-------------|
+| NFR-01.1 | WebSocket-Events werden innerhalb von 500 ms nach Node-Eintritt gesendet. |
+| NFR-01.2 | Blueprint-CRUD-Endpunkte antworten in < 200 ms (P95). |
+| NFR-01.3 | Das System unterstützt ≥ 10 parallele Council-Runs. |
+
+### NFR-02: Sicherheit
+
+| ID | Anforderung |
+|----|-------------|
+| NFR-02.1 | API-Keys (Anthropic, OpenAI, Tavily) werden ausschließlich in Umgebungsvariablen gespeichert, nie im Code. |
+| NFR-02.2 | Keine echten LLM-API-Aufrufe in CI/CD-Tests. |
+| NFR-02.3 | CORS ist auf bekannte Origins beschränkt (in Produktion). |
+
+### NFR-03: Wartbarkeit
+
+| ID | Anforderung |
+|----|-------------|
+| NFR-03.1 | Backend-Testabdeckung: ≥ 80 % für `agents/`, ≥ 90 % für `state.py` und `services/graph_builder.py`. |
+| NFR-03.2 | Datenbankmigrationen werden mit Alembic verwaltet. |
+| NFR-03.3 | Der LangGraph-Graph wird ab Phase 3 dynamisch aus Blueprint-JSON gebaut (kein hartcodierter Graph in Produktion). |
+
+### NFR-04: Skalierbarkeit
+
+| ID | Anforderung |
+|----|-------------|
+| NFR-04.1 | LangGraph-Runs werden in asyncio-Thread-Pools ausgeführt, um den FastAPI Event Loop nicht zu blockieren. |
+| NFR-04.2 | WebSocket-Sessions sind pro `run_id` isoliert — keine Event-Übertragung zwischen Sessions. |
+
+---
+
+## 6. Technische Abhängigkeiten
+
+| Komponente | Technologie | Version |
+|------------|-------------|---------|
+| KI-Orchestrierung | LangGraph (Python) | ≥ 0.2.x |
+| Backend-API | FastAPI | ≥ 0.110 |
+| Frontend-Framework | Next.js + React Flow | Next.js 14+, React Flow 12+ |
+| Datenbank | PostgreSQL | 16 |
+| Vektor-DB | ChromaDB (lokal) | ≥ 0.5 |
+| LLMs | Anthropic Claude 3.5 Sonnet, OpenAI GPT-4o | via API |
+| Web-Suche | Tavily Search API | — |
+| PDF-Verarbeitung | PyPDF + LangChain Text Splitter | — |
+
+---
+
+## 7. Annahmen und Einschränkungen
+
+### Annahmen
+
+- Nutzer haben gültige API-Keys für Anthropic und/oder OpenAI.
+- Die Anwendung wird zunächst lokal (Docker Compose) und später in der Cloud betrieben.
+- Ein PDF-Upload ist auf ≤ 50 MB begrenzt.
+
+### Einschränkungen
+
+- Zyklen sind First-Class — der Graph darf nicht zu einem DAG vereinfacht werden.
+- State ist die einzige Quelle der Wahrheit — Agents speichern keinen internen Zustand.
+- Human-in-the-Loop erfolgt ausschließlich über LangGraphs `interrupt_before` — kein eigener Pause-Mechanismus.
+- WebSocket für Echtzeit-Updates ist Pflicht — Polling ist nicht akzeptabel.
+
+---
+
+## 8. Entwicklungs-Roadmap (Phasen)
+
+| Phase | Ziel | Status |
+|-------|------|--------|
+| Phase 1 — LangGraph Engine (Backend MVP) | Hartcodierter Testgraph, CouncilState, Routing-Logik | ✅ Abgeschlossen |
+| Phase 2 — Visueller Baukasten (Frontend MVP) | React Flow Canvas, Custom Nodes/Edges, Blueprint-Parser, PostgreSQL-Speicherung | ✅ Abgeschlossen |
+| Phase 3 — Integration (Frontend ↔ Backend) | Dynamischer Graph aus JSON-Blueprint, WebSocket-Events, Frontend-Ausgabe | ✅ Abgeschlossen |
+| Phase 4 — Tools & God Mode (Enterprise) | Tavily Search, PyPDF + ChromaDB, Human-in-the-Loop UI | ✅ Abgeschlossen |
+
+---
+
+## 9. Typische Use-Cases
+
+### Use-Case 1: Content-Rat
+
+```
+User Input → Master-KI (schreibt Rohfassung)
+           → Kritiker-KI (prüft Fakten & SEO)
+           → [Wenn Note < 8: zurück zu Master-KI]
+           → Lektor-KI (formatiert für Social Media)
+```
+
+### Use-Case 2: Programmier-Rat
+
+```
+User Input → Architekt-KI (schreibt Code)
+           → Tester-KI (sucht Bugs)
+           → [Wenn Bugs: zurück zum Architekten]
+           → Doku-KI (schreibt das README)
+```
+
+### Use-Case 3: Analyse-Rat
+
+```
+PDF-Upload → Researcher-KI (liest 100-seitiges PDF)
+           → Analyst-KI (extrahiert Kerndaten)
+           → Strategie-KI (schreibt Zusammenfassung)
+```
+
+---
+
+## 10. Glossar
+
+| Begriff | Definition |
+|---------|------------|
+| Council | Eine konfigurierte Gruppe von KI-Agents, die zusammenarbeiten |
+| Blueprint | Die gespeicherte JSON-Konfiguration eines Councils |
+| Council Run | Eine einzelne Ausführung eines Councils |
+| CouncilState | Das zentrale TypedDict, das zwischen allen Agents weitergegeben wird |
+| God Mode | Ausführungsmodus mit menschlicher Genehmigung an jedem Entscheidungspunkt |
+| Auto-Pilot | Ausführungsmodus ohne menschlichen Eingriff |
+| Node | Ein einzelner KI-Agent im Graph |
+| Edge | Eine Verbindung zwischen zwei Agents (linear oder bedingt) |
+| Critic Score | Die numerische Bewertung (0–10) des Kritiker-Agents |
+| Route Decision | Das Routing-Signal (`rework`\|`approve`\|benutzerdefiniert) |

_bmad-output/planning-artifacts/ux-design.md

@@ -0,0 +1,290 @@
+---
+stepsCompleted:
+  - step-01-init
+  - step-02-discovery
+  - step-03-core-experience
+  - step-04-emotional-response
+  - step-05-inspiration
+  - step-06-design-system
+  - step-07-defining-experience
+  - step-08-visual-foundation
+  - step-09-design-directions
+  - step-10-user-journeys
+  - step-11-component-strategy
+  - step-12-ux-patterns
+  - step-13-responsive-accessibility
+  - step-14-complete
+inputDocuments:
+  - _bmad-output/planning-artifacts/prd.md
+  - README.md
+---
+
+# UX Design Dokument — CouncilOS
+
+**Autor:** KI-Konzil Dev-Team
+**Datum:** 2026-03-12
+**Version:** 1.0.0
+**Bezug:** PRD v1.0.0
+
+---
+
+## 1. Design-Vision
+
+CouncilOS gibt dem Nutzer das Gefühl, **Dirigent eines KI-Orchesters** zu sein. Die Oberfläche kommuniziert Kontrolle, Transparenz und intellektuelle Kraft — ohne technisches Fachwissen vorauszusetzen.
+
+**Kernwerte des Designs:**
+- **Klarheit über Komplexität** — Komplexe Agent-Pipelines müssen auf einen Blick verstehbar sein.
+- **Lebendige Transparenz** — Der Nutzer sieht immer, was die KI gerade tut (pulsierender Node, Live-Text).
+- **Vertrauen durch Kontrolle** — God Mode gibt das Gefühl, Herr der Lage zu sein.
+
+---
+
+## 2. Nutzererfahrungs-Ziele
+
+| Ziel | Messgröße |
+|------|-----------|
+| Nutzer baut ersten Council in < 5 Minuten | Zeit bis zur ersten erfolgreichen Speicherung |
+| Nutzer versteht sofort, welcher Agent aktiv ist | Qualitative Usability-Tests |
+| God Mode-Popup ist selbsterklärend | Anteil Nutzer, die ohne Anleitung genehmigen/ablehnen können |
+
+---
+
+## 3. Informationsarchitektur
+
+```
+CouncilOS
+├── Tab A: Rat-Architekt (Setup Mode)
+│   ├── Infinite Canvas (React Flow)
+│   │   ├── Agent-Nodes (verschiebbar, verbindbar)
+│   │   └── Edges (linear + bedingt)
+│   ├── Linke Seitenleiste: Node-Bibliothek (Drag-Quelle)
+│   ├── Rechte Seitenleiste: Node/Edge-Einstellungen (kontextuell)
+│   └── Top-Bar: Council-Name, Speichern, Export
+│
+└── Tab B: Konferenzzimmer (Execution Mode)
+    ├── Eingabebereich (Prompt + PDF-Upload)
+    ├── Mode-Toggle (Auto-Pilot / God Mode)
+    ├── Live-Diagramm-View (schreibgeschützter Canvas)
+    ├── Output-Bereich (wachsendes Dokument)
+    └── God Mode Approval-Overlay (situativ)
+```
+
+---
+
+## 4. UI-Komponenten
+
+### 4.1 Agent-Node (Canvas-Element)
+
+```
+┌─────────────────────────────┐
+│  🤖  Master KI              │  ← Name
+│  ─────────────────────────  │
+│  Claude 3.5 Sonnet          │  ← LLM-Modell
+│  🔍 Web-Suche  📄 PDF      │  ← Tool-Badges
+└─────────────────────────────┘
+         ●──── (Verbindungspunkte)
+```
+
+**Zustände:**
+- **Standard:** Grauer Rahmen, weißer Hintergrund
+- **Ausgewählt:** Blauer Rahmen, leichter Schatten
+- **Aktiv (laufend):** Pulsierender gelber Glow-Effekt (via CSS-Animation)
+- **Abgeschlossen:** Grüner Rand (kurz, dann wieder Standard)
+- **Fehler:** Roter Rand
+
+### 4.2 Edge (Verbindungspfeil)
+
+| Edge-Typ | Darstellung | Bedeutung |
+|----------|-------------|-----------|
+| Linear | Durchgehende graue Linie mit Pfeil | Immer weiterleiten |
+| Bedingt (rework) | Gestrichelte rote Linie mit Label | Bei Fehlern zurück |
+| Bedingt (approve) | Durchgehende grüne Linie mit Label | Bei Genehmigung weiter |
+
+### 4.3 Node-Einstellungs-Panel (Seitenleiste rechts)
+
+```
+┌─────────────────────────────────────┐
+│  Node-Einstellungen                 │
+│  ─────────────────────────────────  │
+│  Name:        [__________________]  │
+│                                     │
+│  System-Prompt:                     │
+│  [                               ]  │
+│  [  Du bist ein Content-Experte  ]  │
+│  [                               ]  │
+│                                     │
+│  LLM-Modell:  [Claude 3.5 Sonnet▼] │
+│                                     │
+│  Tools:                             │
+│  🔍 Web-Suche    ○────●             │
+│  📄 PDF-Reader   ○────○             │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+### 4.4 God Mode Approval-Overlay
+
+```
+┌─────────────────────────────────────────────┐
+│  ⏸  God Mode — Warte auf Genehmigung        │
+│  ─────────────────────────────────────────  │
+│  Agent „Kritiker KI" schlägt vor:           │
+│                                             │
+│  🔁 Das Dokument an „Master KI" zurück-     │
+│     weisen.                                 │
+│                                             │
+│  Grund: „Score 6/10 — Zu wenig Details"    │
+│                                             │
+│  Aktuelles Dokument:                        │
+│  ┌─────────────────────────────────────┐   │
+│  │  Lorem ipsum...                     │   │
+│  └─────────────────────────────────────┘   │
+│                                             │
+│  [✅ Genehmigen]  [✏️ Modifizieren]  [❌ Ablehnen] │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## 5. User Journey: Ersten Council erstellen
+
+```
+1. Nutzer öffnet CouncilOS
+   └─► Rat-Architekt Tab wird angezeigt (leerer Canvas)
+
+2. Nutzer zieht „Agent"-Node aus der Seitenleiste
+   └─► Node erscheint auf dem Canvas mit Default-Einstellungen
+
+3. Nutzer klickt auf den Node
+   └─► Rechtes Panel öffnet sich: Name, System-Prompt, Modell, Tools
+
+4. Nutzer benennt Node „Master KI" und gibt System-Prompt ein
+   └─► Canvas-Node aktualisiert sich live
+
+5. Nutzer zieht zweiten Node (Kritiker KI) und verbindet sie
+   └─► Edge-Pfeil erscheint
+
+6. Nutzer markiert Rück-Edge als bedingt „rework"
+   └─► Gestrichelte rote Linie mit Label
+
+7. Nutzer gibt Council-Namen ein (oben) und klickt „Speichern"
+   └─► Council wird in PostgreSQL gespeichert, Bestätigung erscheint
+```
+
+---
+
+## 6. User Journey: Council ausführen (Auto-Pilot)
+
+```
+1. Nutzer wechselt zum Konferenzzimmer-Tab
+
+2. Nutzer tippt Prompt: „Schreibe einen Blogartikel über KI-Trends 2025"
+
+3. Nutzer wählt „Auto-Pilot" und klickt „Starten"
+   └─► HTTP POST → 202 Accepted, run_id zurück
+   └─► WebSocket-Verbindung wird geöffnet
+
+4. „Master KI"-Node pulsiert gelb
+   └─► WebSocket-Event: {"node": "master_agent", "status": "running"}
+
+5. „Kritiker KI"-Node pulsiert gelb
+   └─► WebSocket-Event: {"node": "critic_agent", "status": "running"}
+
+6. Rwork-Schleife (falls Score < 8):
+   └─► Roter Rand kurz bei Master-Node → wieder gelb
+
+7. „Writer KI"-Node pulsiert → grüner Rand
+   └─► WebSocket-Event: {"node": "writer_agent", "status": "completed"}
+
+8. Finales Dokument erscheint im Output-Bereich
+   └─► WebSocket-Event: {"status": "done"}
+```
+
+---
+
+## 7. User Journey: God Mode
+
+```
+1. Nutzer wählt „God Mode" im Toggle
+
+2. Erster Node startet → pulsiert
+   └─► Nach Node-Abschluss: Overlay erscheint
+
+3. Overlay zeigt: Agent-Name, Vorschlag, Grund, aktuelles Dokument
+
+4. Nutzer wählt „Genehmigen"
+   └─► POST /approve → nächster Node startet
+
+5. Nutzer wählt „Modifizieren"
+   └─► Dokument-Editierfeld wird aktiv
+   └─► Nutzer bearbeitet Text → Klick „Fortfahren"
+   └─► Modifizierter State wird an Backend gesendet
+
+6. Nutzer wählt „Ablehnen"
+   └─► Run wird als fehlgeschlagen markiert
+   └─► Benachrichtigung: „Run abgebrochen"
+```
+
+---
+
+## 8. Visuelles Design-System
+
+### 8.1 Farbpalette
+
+| Token | Wert | Verwendung |
+|-------|------|-----------|
+| `--color-primary` | `#3B82F6` (Blau) | Ausgewählte Nodes, Buttons |
+| `--color-active` | `#F59E0B` (Amber) | Aktiv laufender Node (Glow) |
+| `--color-success` | `#10B981` (Grün) | Abgeschlossener Node, Approve |
+| `--color-danger` | `#EF4444` (Rot) | Fehler-Node, Reject, rework-Edge |
+| `--color-bg` | `#F8FAFC` | Canvas-Hintergrund |
+| `--color-node-bg` | `#FFFFFF` | Node-Hintergrund |
+| `--color-border` | `#E2E8F0` | Node-Standard-Rahmen |
+| `--color-text` | `#1E293B` | Primärtext |
+| `--color-text-muted` | `#64748B` | Sekundärtext |
+
+### 8.2 Typografie
+
+| Ebene | Font | Größe | Gewicht |
+|-------|------|-------|---------|
+| UI-Labels | Inter / System-UI | 14px | 500 |
+| Node-Name | Inter | 15px | 600 |
+| System-Prompt | Inter (Monospace für Code) | 13px | 400 |
+| Output-Text | Inter | 16px | 400 |
+
+### 8.3 Animationen
+
+| Animation | Beschreibung |
+|-----------|--------------|
+| `pulse-glow` | Aktiver Node: 0.8s-Keyframe-Animation, Amber-Box-Shadow pulsiert |
+| `node-complete` | Grüner Rand für 1,5 Sekunden nach Abschluss |
+| `overlay-slide-in` | God Mode Overlay: 150ms Ease-in-out von unten |
+
+---
+
+## 9. Responsive Design & Accessibility
+
+| Aspekt | Anforderung |
+|--------|-------------|
+| Mindest-Viewport | 1280 × 768 px (Desktop-Fokus; kein Mobile MVP) |
+| Keyboard-Navigation | Canvas-Nodes per Tab erreichbar |
+| Aria-Labels | Alle Buttons und interaktiven Elemente mit `aria-label` |
+| Farbkontrast | WCAG AA — Textverhältnis ≥ 4.5:1 |
+| Fokus-Sichtbarkeit | Deutlicher Fokus-Ring bei Keyboard-Navigation |
+
+---
+
+## 10. Komponentenübersicht (Implementiert)
+
+| Komponente | Pfad | Beschreibung |
+|------------|------|--------------|
+| `ArchitectCanvas` | `app/components/ArchitectCanvas.tsx` | React Flow Canvas-Wrapper |
+| `NavTabs` | `app/components/NavTabs.tsx` | Tab-Navigation (Rat-Architekt / Konferenzzimmer) |
+| `NodeSidebar` | `app/components/panels/NodeSidebar.tsx` | Linke Seitenleiste (Drag-Quelle) |
+| `NodeSettingsPanel` | `app/components/panels/NodeSettingsPanel.tsx` | Rechtes Settings-Panel |
+| `EdgeSettingsPanel` | `app/components/panels/EdgeSettingsPanel.tsx` | Edge-Einstellungen |
+| `AgentNode` | `app/components/nodes/` | Custom React Flow Node-Komponente |
+| `ConditionalEdge` | `app/components/edges/` | Custom React Flow Edge-Komponente |
+| `council-store` | `app/store/council-store.ts` | Zustand State Management |
+| `blueprint-parser` | `app/utils/blueprint-parser.ts` | React Flow → Blueprint JSON |
+| `api-client` | `app/utils/api-client.ts` | HTTP-Client |