From 1f33448a352a200e7e5f0541154b47f567f66eee Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 13 Mar 2026 15:30:19 +0000 Subject: [PATCH] Add project documentation from document-project skill (index, overview, source tree) Co-authored-by: Kenearos <86194771+Kenearos@users.noreply.github.com> --- docs/index.md | 148 +++++++++++++++++ docs/project-overview.md | 190 ++++++++++++++++++++++ docs/source-tree-analysis.md | 305 +++++++++++++++++++++++++++++++++++ 3 files changed, 643 insertions(+) create mode 100644 docs/index.md create mode 100644 docs/project-overview.md create mode 100644 docs/source-tree-analysis.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..cefc5cd --- /dev/null +++ b/docs/index.md @@ -0,0 +1,148 @@ +# CouncilOS Documentation Index + +**Type:** Multi-Part Full-Stack Web Application +**Primary Languages:** Python (Backend), TypeScript (Frontend) +**Architecture:** LangGraph Cyclic Multi-Agent Pipeline + React Flow Visual Builder +**Last Updated:** 2026-03-13 + +## Project Overview + +CouncilOS ("KI-Rat Baukasten") ist eine visuelle No-Code-Plattform zum Erstellen und Ausführen von Multi-Agenten-KI-Pipelines. Nutzer bauen per Drag & Drop einen "KI-Rat" aus spezialisierten Agenten, die in zyklischen Schleifen iterativ zusammenarbeiten, bis die gewünschte Ergebnisqualität erreicht ist. + +## Project Structure + +Dieses Projekt besteht aus 2 Hauptteilen: + +### Backend (api) + +- **Type:** FastAPI REST/WebSocket API + LangGraph AI Engine +- **Location:** `backend/` +- **Tech Stack:** Python 3.11+, FastAPI, LangGraph, SQLAlchemy (async), PostgreSQL, ChromaDB +- **Entry Point:** `backend/main.py` + +### Frontend (ui) + +- **Type:** Next.js Single-Page Application mit React Flow Canvas +- **Location:** `frontend/` +- **Tech Stack:** Next.js 14+, React, React Flow (@xyflow/react), Zustand, TypeScript +- **Entry Point:** `frontend/app/page.tsx` + +## Cross-Part Integration + +- Frontend kommuniziert mit Backend via REST API (`/api/councils/*`, `/api/runs/*`) und WebSocket (`/ws/council/{run_id}`) +- Blueprint-JSON ist das kanonische Austauschformat zwischen Frontend und Backend +- WebSocket-Events steuern die Echtzeit-Visualisierung des aktiven Agent-Nodes im Frontend + +## Quick Reference + +### Backend Quick Ref + +- **Stack:** FastAPI, LangGraph, SQLAlchemy, PostgreSQL, ChromaDB +- **Entry:** `backend/main.py` +- **Pattern:** Service Layer → Agent Nodes → LangGraph StateGraph + +### Frontend Quick Ref + +- **Stack:** Next.js, React Flow, Zustand, TypeScript +- **Entry:** `frontend/app/page.tsx` +- **Pattern:** React Flow Canvas → Blueprint Parser → API Client + +## Generated Documentation + +### Core Documentation + +- [Project Overview](./project-overview.md) — Executive Summary und High-Level-Architektur +- [Source Tree Analysis](./source-tree-analysis.md) — Annotierte Verzeichnisstruktur + +### Existing Documentation + +- [Test Coverage Analysis](./test-coverage-analysis.md) — Testabdeckung und QA-Analyse + +### BMAD Planning Artifacts + +- [Product Brief](../_bmad-output/planning-artifacts/product-brief.md) — Produkt-Vision und Scope +- [PRD](../_bmad-output/planning-artifacts/prd.md) — Product Requirements Document +- [Architecture](../_bmad-output/planning-artifacts/architecture.md) — Technische Architektur +- [UX Design](../_bmad-output/planning-artifacts/ux-design.md) — UX-Spezifikation +- [Epics & Stories](../_bmad-output/planning-artifacts/epics.md) — Epic- und Story-Breakdown +- [Implementation Readiness](../_bmad-output/planning-artifacts/implementation-readiness.md) — Implementierungs-Assessment +- [PRD Validation Report](../_bmad-output/planning-artifacts/prd-validation-report.md) — PRD-Qualitätsprüfung +- [Project Context](../_bmad-output/planning-artifacts/project-context.md) — AI-Kontext-Regeln + +### BMAD Implementation Artifacts + +- [Sprint Status](../_bmad-output/implementation-artifacts/sprint-status.yaml) — Aktueller Sprint-Stand +- [Epic 1 Retrospective](../_bmad-output/implementation-artifacts/epic-1-retro-2026-03-12.md) — Projekt-Setup & Infrastruktur +- [Epic 2 Retrospective](../_bmad-output/implementation-artifacts/epic-2-retro-2026-03-12.md) — LangGraph Engine Backend +- [Epic 3 Retrospective](../_bmad-output/implementation-artifacts/epic-3-retro-2026-03-12.md) — Visueller Baukasten Frontend +- [Epic 4 Retrospective](../_bmad-output/implementation-artifacts/epic-4-retro-2026-03-12.md) — Frontend-Backend-Integration +- [Epic 5 Retrospective](../_bmad-output/implementation-artifacts/epic-5-retro-2026-03-12.md) — Tools & God Mode +- [QA E2E Tests](../_bmad-output/implementation-artifacts/qa-e2e-tests.md) — End-to-End-Testplan + +## Getting Started + +### Backend Setup + +**Prerequisites:** Python 3.11+, PostgreSQL 16 (oder Docker) + +```bash +cd backend +python -m venv .venv && source .venv/bin/activate +pip install -r requirements.txt +uvicorn main:app --reload +``` + +### Frontend Setup + +**Prerequisites:** Node.js 18+ + +```bash +cd frontend +npm install +npm run dev +``` + +### Docker Compose (empfohlen) + +**Prerequisites:** Docker, Docker Compose + +```bash +cp .env.example .env +# API-Keys in .env eintragen +docker compose up -d +``` + +### Tests ausführen + +```bash +# Backend (pytest) +cd backend && pytest tests/ -v + +# Frontend (vitest) +cd frontend && npm test +``` + +## For AI-Assisted Development + +This documentation was generated specifically to enable AI agents to understand and extend this codebase. + +### When Planning New Features: + +**UI-only features:** +→ Reference: `_bmad-output/planning-artifacts/architecture.md`, `frontend/app/components/` + +**API/Backend features:** +→ Reference: `_bmad-output/planning-artifacts/architecture.md`, `backend/api/`, `backend/services/` + +**Full-stack features:** +→ Reference: All architecture docs + `CLAUDE.md` for conventions + +**New Agent Tools:** +→ Reference: `backend/tools/`, Factory-Pattern in `backend/services/dynamic_graph_builder.py` + +**Deployment changes:** +→ Reference: `docker-compose.yml`, `backend/Dockerfile`, `frontend/Dockerfile` + +--- + +_Documentation generated by BMAD Method `document-project` workflow_ diff --git a/docs/project-overview.md b/docs/project-overview.md new file mode 100644 index 0000000..f5eb7a5 --- /dev/null +++ b/docs/project-overview.md @@ -0,0 +1,190 @@ +# CouncilOS — Project Overview + +**Date:** 2026-03-13 +**Type:** Multi-Part Full-Stack Web Application +**Architecture:** Cyclic Multi-Agent Pipeline (LangGraph) + Visual Graph Builder (React Flow) + +## Executive Summary + +CouncilOS ist eine visuelle No-Code-Plattform für zyklische Multi-Agenten-KI-Pipelines. Das Projekt besteht aus einem Python-Backend (FastAPI + LangGraph) und einem TypeScript-Frontend (Next.js + React Flow). Nutzer bauen per Drag & Drop einen "KI-Rat" aus spezialisierten Agenten, verbinden sie mit linearen und bedingten Kanten, und führen den Rat entweder autonom (Auto-Pilot) oder mit menschlicher Kontrolle (God Mode) aus. + +**Kern-Differenzierung:** Im Gegensatz zu linearen KI-Pipelines unterstützt CouncilOS **echte Zyklen** — ein Kritiker-Agent kann ein Dokument wiederholt an den Master-Agent zurückweisen, bis die Qualitätsschwelle erreicht ist. + +## Project Classification + +- **Repository Type:** Multi-Part (Backend + Frontend) +- **Project Type(s):** AI Platform, Web Application +- **Primary Languages:** Python 3.11+, TypeScript 5.x +- **Architecture Pattern:** Service-Oriented Backend + Component-Based Frontend + +## Multi-Part Structure + +Dieses Projekt besteht aus 2 Hauptteilen: + +### Backend (`backend/`) + +- **Type:** REST/WebSocket API + AI Engine +- **Purpose:** LangGraph-basierte KI-Orchestrierung, Blueprint-Verwaltung, Run-Management +- **Tech Stack:** FastAPI, LangGraph, SQLAlchemy (async), PostgreSQL, ChromaDB, Anthropic/OpenAI APIs + +### Frontend (`frontend/`) + +- **Type:** Single-Page Application +- **Purpose:** Visueller Canvas zum Erstellen von Agent-Graphen, Live-Execution-Anzeige, God-Mode-UI +- **Tech Stack:** Next.js 14, React Flow (@xyflow/react), Zustand, TypeScript + +### How Parts Integrate + +1. **Blueprint-JSON** ist das kanonische Austauschformat — Frontend erstellt es, Backend konsumiert es +2. **REST API** (`/api/councils/*`, `/api/runs/*`) für CRUD-Operationen und Run-Management +3. **WebSocket** (`/ws/council/{run_id}`) für Echtzeit-Node-Status-Updates +4. **God-Mode-Events** (`run_paused`) triggern das Approval-Overlay im Frontend + +## Technology Stack Summary + +### Backend Stack + +| Kategorie | Technologie | Version | Zweck | +|-----------|-------------|---------|-------| +| Web-Framework | FastAPI | ≥ 0.111 | REST + WebSocket API | +| AI-Orchestrierung | LangGraph | ≥ 0.2.0 | Zyklische Multi-Agent-Graphen | +| LLM-Provider | Anthropic Claude 3.5 Sonnet | via API | Primäres KI-Modell | +| LLM-Provider | OpenAI GPT-4o | via API | Alternatives KI-Modell | +| Datenbank | PostgreSQL 16 | Docker | Blueprint- und Run-Speicherung | +| ORM | SQLAlchemy 2.0+ (async) | asyncpg | Datenbankzugriff | +| Migrationen | Alembic | ≥ 1.13 | Schema-Evolution | +| Vektor-DB | ChromaDB | ≥ 0.5.0 | PDF-Suche (Embeddings) | +| Web-Suche | Tavily API | — | Agent-Tool | +| Tests | pytest + pytest-asyncio | ≥ 8.0 | Unit + Integration Tests | + +### Frontend Stack + +| Kategorie | Technologie | Version | Zweck | +|-----------|-------------|---------|-------| +| Framework | Next.js | 14+ | App Router SSR/CSR | +| Canvas-Bibliothek | React Flow (@xyflow/react) | 12+ | Drag & Drop Graph-Builder | +| State Management | Zustand | — | Canvas- und Run-State | +| Sprache | TypeScript | 5.x | Typsicherheit | +| Styling | Tailwind CSS | — | UI-Design | +| Tests | Vitest | — | Component + Unit Tests | + +## Key Features + +1. **Visueller Canvas (Rat-Architekt):** Drag & Drop Agent-Nodes, konfigurierbare System-Prompts, LLM-Modell-Auswahl, Tool-Toggles (Web-Suche, PDF-Reader) +2. **Lineare & Bedingte Edges:** Workflows mit Verzweigungen und Schleifen definieren +3. **Blueprint-Speicherung:** Council-Konfigurationen als JSON in PostgreSQL speichern und laden +4. **Auto-Pilot-Modus:** Agents laufen autonom bis zum Abschluss +5. **God Mode (Human-in-the-Loop):** LangGraph `interrupt_before` pausiert an jedem Node; Nutzer kann genehmigen, ablehnen oder den Draft modifizieren +6. **Echtzeit-Updates:** WebSocket-Events pulsieren den aktiven Node im Canvas +7. **Agent-Tools:** Tavily Web-Suche und PDF-Upload + ChromaDB-Suche als optionale Agent-Werkzeuge +8. **Run-Verlauf:** Alle Council-Runs mit Ergebnis, Critic-Score und Iterationszahl abrufbar + +## Architecture Highlights + +### LangGraph Cyclic Graph + +``` +Master-Agent → Critic-Agent → [Score < 8: zurück zu Master] → Writer-Agent → END +``` + +- **CouncilState** (TypedDict mit `operator.add`-Reducern) ist die einzige Wahrheitsquelle +- **Safety Valve:** `MAX_ITERATIONS = 5` erzwingt Genehmigung nach 5 Runden +- **Score-basiertes Routing:** Numerischer Critic-Score (nicht LLM-Verdict) bestimmt das Routing + +### Dynamic Graph Builder + +Ab Phase 3 werden Graphen **dynamisch** aus Blueprint-JSON gebaut — kein hartcodierter Graph in Produktion. + +### Factory Pattern für Tools + +`create_web_search_tool()` und `create_pdf_search_tool()` Factories geben `None` zurück wenn API-Keys fehlen — keine Crashes bei fehlender Konfiguration. + +## Development Overview + +### Prerequisites + +- Python 3.11+ (Backend) +- Node.js 18+ (Frontend) +- Docker + Docker Compose (PostgreSQL, optionale Container) + +### Getting Started + +```bash +# 1. Repository klonen +git clone https://github.com/Kenearos/KI-Konzil.git +cd KI-Konzil + +# 2. Umgebungsvariablen konfigurieren +cp .env.example .env +# ANTHROPIC_API_KEY, OPENAI_API_KEY, TAVILY_API_KEY eintragen + +# 3. Docker Compose starten (PostgreSQL + Services) +docker compose up -d +``` + +### Key Commands + +#### Backend + +- **Install:** `pip install -r backend/requirements.txt` +- **Dev:** `cd backend && uvicorn main:app --reload` +- **Test:** `cd backend && pytest tests/ -v` + +#### Frontend + +- **Install:** `cd frontend && npm install` +- **Dev:** `cd frontend && npm run dev` +- **Test:** `cd frontend && npm test` + +## Repository Structure + +``` +KI-Konzil/ +├── backend/ → FastAPI + LangGraph Backend +│ ├── agents/ → Agent-Node-Funktionen (Master, Critic, Writer) +│ ├── api/ → REST/WebSocket-Routen +│ ├── services/ → Graph-Builder, Blueprint-Service, Run-Service +│ ├── models/ → SQLAlchemy ORM-Modelle +│ ├── tools/ → Web-Suche, PDF-Reader +│ ├── tests/ → 10 pytest-Testdateien (125+ Tests) +│ └── alembic/ → Datenbankmigrationen +├── frontend/ → Next.js + React Flow Frontend +│ └── app/ +│ ├── components/ → Canvas, Nodes, Edges, Panels +│ ├── hooks/ → useCouncilWebSocket +│ ├── store/ → Zustand Council-Store +│ ├── utils/ → Blueprint-Parser, API-Client +│ └── __tests__/ → 4 vitest-Testdateien (26+ Tests) +├── _bmad-output/ → BMAD Planning & Implementation Artifacts +├── docs/ → Projektdokumentation +└── docker-compose.yml → Lokale Entwicklungsumgebung +``` + +## Quantitative Summary + +| Metrik | Wert | +|--------|------| +| Backend Python-Dateien | 38 | +| Frontend TS/TSX-Dateien | 23 | +| Backend Lines of Code | ~4.567 | +| Frontend Lines of Code | ~2.070 | +| Backend-Tests | 125+ (10 Testdateien) | +| Frontend-Tests | 26+ (4 Testdateien) | +| Epics | 5 (alle abgeschlossen) | +| Stories | 18 (alle abgeschlossen) | +| API-Endpunkte | 8 REST + 1 WebSocket | +| DB-Tabellen | 2 (blueprints, council_runs) | + +## Documentation Map + +For detailed information, see: + +- [index.md](./index.md) — Master Documentation Index +- [source-tree-analysis.md](./source-tree-analysis.md) — Annotierte Verzeichnisstruktur +- [Architecture](../_bmad-output/planning-artifacts/architecture.md) — Detaillierte Systemarchitektur +- [PRD](../_bmad-output/planning-artifacts/prd.md) — Product Requirements Document +- [CLAUDE.md](../CLAUDE.md) — AI-Konventionen und Coding-Standards + +--- + +_Generated using BMAD Method `document-project` workflow_ diff --git a/docs/source-tree-analysis.md b/docs/source-tree-analysis.md new file mode 100644 index 0000000..8315b4a --- /dev/null +++ b/docs/source-tree-analysis.md @@ -0,0 +1,305 @@ +# CouncilOS — Source Tree Analysis + +**Date:** 2026-03-13 + +## Overview + +CouncilOS ist ein Multi-Part Full-Stack-Projekt mit klar getrenntem Python-Backend und TypeScript-Frontend. Die Verzeichnisstruktur folgt etablierten Konventionen für FastAPI (Backend) und Next.js App Router (Frontend). + +## Multi-Part Structure + +Dieses Projekt ist in 2 Hauptteile organisiert: + +- **Backend** (`backend/`): FastAPI REST/WebSocket API + LangGraph AI Engine +- **Frontend** (`frontend/`): Next.js App mit React Flow Canvas + +## Complete Directory Structure + +``` +KI-Konzil/ +├── .claude/commands/ # BMAD Claude Code Skill-Definitionen (42 Dateien) +├── .env.example # Template für Umgebungsvariablen +├── .gitignore # Git-Ausschlüsse (.env, node_modules, __pycache__, etc.) +├── CLAUDE.md # AI-Konventionen und Projekt-Kontext +├── README.md # Deutsche Projektbeschreibung (Ursprungs-PRD) +│ +├── _bmad/ # BMAD Method v6 Installation +│ ├── _config/ # Agent-Manifeste, Tool-Manifeste +│ ├── _memory/ # Agent-Erinnerungen +│ ├── bmm/ # Business Method Module +│ │ ├── agents/ # Agent-Definitionen (analyst, architect, dev, pm, qa, sm, ux) +│ │ ├── config.yaml # Modul-Konfiguration (Sprache: Deutsch) +│ │ ├── data/ # PRD-Vorlagen, Projekt-Templates +│ │ ├── teams/ # Team-Kompositionen +│ │ └── workflows/ # BMAD-Workflow-Definitionen +│ │ ├── 1-analysis/ # Product Brief, Research +│ │ ├── 2-plan-workflows/ # PRD, UX Design +│ │ ├── 3-solutioning/ # Architecture, Epics, Implementation Readiness +│ │ ├── 4-implementation/ # Sprint Planning, Stories, Dev, Code Review, Retro +│ │ ├── document-project/ # Projekt-Dokumentation (dieses Dokument) +│ │ ├── generate-project-context/ # AI-Kontext generieren +│ │ ├── qa-generate-e2e-tests/ # QA Test-Generierung +│ │ └── bmad-quick-flow/ # Quick Spec + Dev Workflow +│ └── core/ # BMAD Core (Tasks, Workflows, Agents) +│ +├── _bmad-output/ # BMAD generierte Artefakte +│ ├── planning-artifacts/ # Product Brief, PRD, Architecture, UX, Epics +│ │ ├── product-brief.md # ← Analyst Agent (Mary) +│ │ ├── prd.md # ← PM Agent (John) +│ │ ├── prd-validation-report.md # ← PRD Validation +│ │ ├── architecture.md # ← Architect Agent (Winston) +│ │ ├── ux-design.md # ← UX Designer Agent +│ │ ├── epics.md # ← PM Agent (John) +│ │ ├── implementation-readiness.md # ← Architect Agent (Winston) +│ │ └── project-context.md # ← Generate Project Context +│ └── implementation-artifacts/ # Sprint Status, Stories, Retros +│ ├── sprint-status.yaml # Sprint-Tracking (alle 5 Epics: done) +│ ├── stories/ # 20 Story-Dateien (alle: done) +│ ├── epic-1-retro-*.md # Retrospektive Epic 1 +│ ├── epic-2-retro-*.md # Retrospektive Epic 2 +│ ├── epic-3-retro-*.md # Retrospektive Epic 3 +│ ├── epic-4-retro-*.md # Retrospektive Epic 4 +│ ├── epic-5-retro-*.md # Retrospektive Epic 5 +│ └── qa-e2e-tests.md # E2E-Testplan +│ +├── backend/ # ★ Python FastAPI Backend +│ ├── Dockerfile # Python 3.11 + Uvicorn +│ ├── main.py # ★ FastAPI App Entrypoint +│ ├── state.py # ★ CouncilState TypedDict + Konstanten +│ ├── database.py # Async SQLAlchemy Engine + Session Factory +│ ├── requirements.txt # Python-Abhängigkeiten +│ ├── pytest.ini # pytest-Konfiguration (asyncio_mode=auto) +│ │ +│ ├── agents/ # ★ LangGraph Agent-Node-Funktionen +│ │ ├── __init__.py +│ │ ├── master_agent.py # Master-Agent: erstellt/überarbeitet Drafts +│ │ ├── critic_agent.py # Critic-Agent: bewertet Drafts (Score 0-10) +│ │ └── writer_agent.py # Writer-Agent: formatiert finalen Output +│ │ +│ ├── api/ # FastAPI Route-Definitionen +│ │ ├── __init__.py +│ │ ├── routes.py # Council Run: POST /api/councils/run, GET .../run/{id} +│ │ ├── blueprint_routes.py # Blueprint CRUD: /api/councils/ +│ │ ├── run_history_routes.py # Run History: GET /api/runs/ +│ │ ├── run_store.py # In-Memory Run Store (Thread-safe) +│ │ └── websocket.py # WS /ws/council/{run_id} — Echtzeit-Events +│ │ +│ ├── services/ # Business-Logik +│ │ ├── __init__.py +│ │ ├── graph_builder.py # Phase 1: Hartcodierter LangGraph-Graph +│ │ ├── dynamic_graph_builder.py # ★ Phase 3+: Dynamischer Graph aus Blueprint-JSON +│ │ ├── blueprint_service.py # Blueprint-CRUD via SQLAlchemy +│ │ └── run_service.py # Run-CRUD via SQLAlchemy +│ │ +│ ├── models/ # SQLAlchemy ORM-Modelle +│ │ ├── __init__.py +│ │ ├── blueprint.py # Blueprint-Tabelle (UUID, JSONB nodes/edges) +│ │ └── council_run.py # CouncilRun-Tabelle (Status, Draft, Score) +│ │ +│ ├── tools/ # Agent-Tools +│ │ ├── __init__.py +│ │ ├── web_search.py # Tavily Web-Suche + Factory-Funktion +│ │ └── pdf_reader.py # PyPDF + ChromaDB + Factory-Funktion +│ │ +│ ├── alembic/ # Datenbankmigrationen +│ │ ├── alembic.ini # Alembic-Konfiguration +│ │ ├── env.py # Async Migration-Environment +│ │ ├── script.py.mako # Migration-Template +│ │ └── versions/ +│ │ ├── 001_create_blueprints_table.py +│ │ └── 002_create_council_runs_table.py +│ │ +│ └── tests/ # ★ pytest Test-Suite (125+ Tests) +│ ├── __init__.py +│ ├── test_state.py # CouncilState-Validierung (9 Tests) +│ ├── test_routing.py # Critic-Parsing + Routing-Logik (21 Tests) +│ ├── test_run_store.py # In-Memory Store CRUD (10 Tests) +│ ├── test_api.py # REST-Endpunkte (20+ Tests) +│ ├── test_blueprint_api.py # Blueprint-CRUD API +│ ├── test_blueprint_service.py # Blueprint-Service (20+ Tests) +│ ├── test_run_service.py # Run-Service (15+ Tests) +│ ├── test_dynamic_graph_builder.py # Dynamischer Graph-Builder +│ ├── test_god_mode.py # God Mode / Human-in-the-Loop +│ └── test_tools.py # Web-Suche + PDF-Reader +│ +├── frontend/ # ★ Next.js + React Flow Frontend +│ ├── Dockerfile # Node.js 18 Multi-Stage Build +│ ├── .dockerignore +│ ├── .gitignore +│ ├── README.md # Frontend-README +│ ├── package.json # Dependencies + Scripts +│ ├── package-lock.json +│ ├── next.config.ts # Next.js-Konfiguration +│ ├── tsconfig.json # TypeScript-Konfiguration +│ ├── eslint.config.mjs # ESLint-Konfiguration +│ ├── postcss.config.mjs # PostCSS (Tailwind) +│ ├── vitest.config.ts # Vitest Test-Konfiguration +│ │ +│ ├── app/ # ★ Next.js App Router +│ │ ├── page.tsx # Landing Page (Redirect) +│ │ ├── layout.tsx # Root Layout + Navigation +│ │ ├── globals.css # Globale Styles (Tailwind) +│ │ ├── favicon.ico +│ │ │ +│ │ ├── rat-architekt/ # Tab A: Visueller Canvas +│ │ │ └── page.tsx # ArchitectCanvas-Seite +│ │ │ +│ │ ├── konferenzzimmer/ # Tab B: Live-Execution +│ │ │ └── page.tsx # Konferenzzimmer-Seite +│ │ │ +│ │ ├── components/ # React-Komponenten +│ │ │ ├── ArchitectCanvas.tsx # ★ Haupt-Canvas (React Flow) +│ │ │ ├── NavTabs.tsx # Tab-Navigation +│ │ │ ├── nodes/ # Custom React Flow Node-Komponenten +│ │ │ ├── edges/ # Custom React Flow Edge-Komponenten +│ │ │ └── panels/ # Settings-Panels (Node, Edge, God Mode) +│ │ │ +│ │ ├── hooks/ # Custom React Hooks +│ │ │ └── useCouncilWebSocket.ts # WebSocket-Hook für Live-Updates +│ │ │ +│ │ ├── store/ # Zustand State Management +│ │ │ └── council-store.ts # Globaler Council-Store +│ │ │ +│ │ ├── types/ # TypeScript-Typen +│ │ │ └── council.ts # AgentNodeData, BlueprintNode, etc. +│ │ │ +│ │ ├── utils/ # Utility-Funktionen +│ │ │ ├── blueprint-parser.ts # parseGraphToBlueprint() +│ │ │ └── api-client.ts # REST API Client +│ │ │ +│ │ └── __tests__/ # ★ Vitest Tests (26+ Tests) +│ │ ├── blueprint-parser.test.ts +│ │ ├── council-store.test.ts +│ │ ├── api-client.test.ts +│ │ └── types.test.ts +│ │ +│ └── public/ # Statische Assets +│ ├── file.svg, globe.svg, next.svg, vercel.svg, window.svg +│ +├── docs/ # Projektdokumentation +│ ├── index.md # ★ Dokumentations-Index +│ ├── project-overview.md # ★ Projekt-Übersicht +│ ├── source-tree-analysis.md # ★ Dieses Dokument +│ └── test-coverage-analysis.md # QA Testabdeckungs-Analyse +│ +└── docker-compose.yml # ★ Lokale Dev-Umgebung (db + api + frontend) +``` + +## Critical Directories + +### `backend/agents/` + +Enthält die drei Kern-Agent-Node-Funktionen, die im LangGraph-Graphen als Nodes registriert werden. + +**Purpose:** KI-Agent-Logik (Prompt-Engineering, LLM-Aufrufe, State-Updates) +**Contains:** `master_agent.py`, `critic_agent.py`, `writer_agent.py` +**Entry Points:** Jede Datei exportiert eine `*_agent_node(state: CouncilState)` Funktion +**Integration:** Wird von `services/graph_builder.py` und `services/dynamic_graph_builder.py` importiert + +### `backend/services/` + +Business-Logik-Schicht zwischen API und Datenbank/LangGraph. + +**Purpose:** Graph-Konstruktion, Blueprint-CRUD, Run-Management +**Contains:** `graph_builder.py` (Phase 1), `dynamic_graph_builder.py` (Phase 3+), `blueprint_service.py`, `run_service.py` +**Entry Points:** `build_council_graph()`, `build_graph_from_blueprint()`, `run_council_async()` +**Integration:** API-Routen rufen Services auf; Services rufen Agents und DB auf + +### `backend/api/` + +FastAPI-Route-Definitionen (REST + WebSocket). + +**Purpose:** HTTP-Endpunkte und WebSocket-Verbindungen +**Contains:** `routes.py`, `blueprint_routes.py`, `run_history_routes.py`, `websocket.py`, `run_store.py` +**Entry Points:** Registriert als Router in `main.py` + +### `backend/tools/` + +Optional aktivierbare Agent-Werkzeuge. + +**Purpose:** Web-Suche (Tavily) und PDF-Reader (ChromaDB) als LangChain-Tools +**Contains:** `web_search.py`, `pdf_reader.py` +**Integration:** Via Factory-Pattern (`create_web_search_tool()`, `create_pdf_search_tool()`) in `dynamic_graph_builder.py` + +### `frontend/app/components/` + +React-Komponenten für Canvas, Nodes, Edges und Panels. + +**Purpose:** Visuelle Darstellung des Agent-Graphen +**Contains:** `ArchitectCanvas.tsx`, `NavTabs.tsx`, `nodes/`, `edges/`, `panels/` +**Integration:** Verwendet React Flow Custom Nodes/Edges, Zustand-Store + +### `frontend/app/utils/` + +Reine Utility-Funktionen ohne Side-Effects. + +**Purpose:** Blueprint-Parser (Canvas → JSON) und API-Client (REST-Aufrufe) +**Contains:** `blueprint-parser.ts`, `api-client.ts` +**Integration:** Vom Zustand-Store und den Komponenten aufgerufen + +## Entry Points + +### Backend + +- **Main Entry:** `backend/main.py` — FastAPI-App mit CORS, Routen, Health-Check +- **Bootstrap:** `uvicorn main:app --reload` oder Docker + +### Frontend + +- **Main Entry:** `frontend/app/page.tsx` — Redirect zu `/rat-architekt` +- **Bootstrap:** `npm run dev` oder Docker + +## File Organization Patterns + +### Backend (Python) + +| Pattern | Purpose | Beispiele | +|---------|---------|-----------| +| `agents/*_agent.py` | LangGraph-Node-Funktionen | `master_agent.py`, `critic_agent.py` | +| `api/*_routes.py` | FastAPI-Router | `blueprint_routes.py`, `run_history_routes.py` | +| `services/*_service.py` | Business-Logik | `blueprint_service.py`, `run_service.py` | +| `models/*.py` | SQLAlchemy ORM-Modelle | `blueprint.py`, `council_run.py` | +| `tests/test_*.py` | pytest-Tests | `test_routing.py`, `test_api.py` | + +### Frontend (TypeScript) + +| Pattern | Purpose | Beispiele | +|---------|---------|-----------| +| `components/*.tsx` | React-Komponenten | `ArchitectCanvas.tsx`, `NavTabs.tsx` | +| `components/nodes/*.tsx` | Custom React Flow Nodes | Agent-Node-Typen | +| `components/edges/*.tsx` | Custom React Flow Edges | Linear, Conditional | +| `hooks/use*.ts` | Custom React Hooks | `useCouncilWebSocket.ts` | +| `store/*-store.ts` | Zustand-Stores | `council-store.ts` | +| `utils/*.ts` | Reine Utility-Funktionen | `blueprint-parser.ts`, `api-client.ts` | +| `__tests__/*.test.ts` | Vitest-Tests | `blueprint-parser.test.ts` | + +## Configuration Files + +| Datei | Beschreibung | +|-------|-------------| +| `.env.example` | Template für API-Keys und DB-URL | +| `.gitignore` | Git-Ausschlüsse | +| `CLAUDE.md` | AI-Konventionen und Projekt-Kontext | +| `docker-compose.yml` | Docker-Service-Orchestrierung (db, api, frontend) | +| `backend/requirements.txt` | Python-Abhängigkeiten | +| `backend/pytest.ini` | pytest-Konfiguration (`asyncio_mode = auto`) | +| `backend/alembic/alembic.ini` | Alembic-Migrations-Konfiguration | +| `frontend/package.json` | Node.js-Abhängigkeiten und Scripts | +| `frontend/tsconfig.json` | TypeScript-Kompiler-Konfiguration | +| `frontend/next.config.ts` | Next.js-Konfiguration | +| `frontend/eslint.config.mjs` | ESLint-Regeln | +| `frontend/vitest.config.ts` | Vitest-Test-Konfiguration | +| `_bmad/bmm/config.yaml` | BMAD-Modul-Konfiguration (Sprache: Deutsch) | + +## Notes for Development + +- **Backend-Tests** laufen ohne Docker — SQLite in-memory wird für alle Tests verwendet +- **Frontend-Tests** laufen ohne Backend — API-Calls werden in Tests gemockt +- **Keine echten LLM-Aufrufe** in CI/Tests — alle Agent-Tests verwenden gemockte LLMs +- **TypedDict `CouncilState`** ist die einzige Wahrheitsquelle — Agents speichern keinen internen Zustand +- **Factory-Pattern für Tools** — `create_web_search_tool()` / `create_pdf_search_tool()` geben `None` zurück wenn API-Keys fehlen +- **Blueprint-JSON** ist das kanonische Format — Frontend erstellt es, Backend konsumiert es + +--- + +_Generated using BMAD Method `document-project` workflow_