its-consulting/KI-Konzil
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add project documentation from document-project skill (index, overview, source tree)

Browse source 
Co-authored-by: Kenearos <86194771+Kenearos@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot] 2026-03-13 15:30:19 +00:00
parent 85a103b04f
commit 1f33448a35
3 changed files with 643 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

148
docs/index.md Normal file
View file

@ -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_

190
docs/project-overview.md Normal file
View file

@ -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_

305
docs/source-tree-analysis.md Normal file
View file

@ -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_