From e37cb6f4c0944978f1c4fd93b6b9edaab4158a50 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 12 Mar 2026 14:14:41 +0000 Subject: [PATCH] Add BMAD planning artifacts: PRD, Architecture, UX Design (pre-skill attribution) Co-authored-by: Kenearos <86194771+Kenearos@users.noreply.github.com> --- .../planning-artifacts/architecture.md | 424 ++++++++++++++++++ _bmad-output/planning-artifacts/prd.md | 272 +++++++++++ _bmad-output/planning-artifacts/ux-design.md | 290 ++++++++++++ 3 files changed, 986 insertions(+) create mode 100644 _bmad-output/planning-artifacts/architecture.md create mode 100644 _bmad-output/planning-artifacts/prd.md create mode 100644 _bmad-output/planning-artifacts/ux-design.md diff --git a/_bmad-output/planning-artifacts/architecture.md b/_bmad-output/planning-artifacts/architecture.md new file mode 100644 index 0000000..5d48d4b --- /dev/null +++ b/_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 +``` diff --git a/_bmad-output/planning-artifacts/prd.md b/_bmad-output/planning-artifacts/prd.md new file mode 100644 index 0000000..e2af62a --- /dev/null +++ b/_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) | diff --git a/_bmad-output/planning-artifacts/ux-design.md b/_bmad-output/planning-artifacts/ux-design.md new file mode 100644 index 0000000..901721d --- /dev/null +++ b/_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 |