KI-Konzil/docs/source-tree-analysis.md

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