Add project documentation from document-project skill (index, overview, source tree)
Co-authored-by: Kenearos <86194771+Kenearos@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
parent
85a103b04f
commit
1f33448a35
3 changed files with 643 additions and 0 deletions
305
docs/source-tree-analysis.md
Normal file
305
docs/source-tree-analysis.md
Normal 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_
|
||||
Loading…
Add table
Add a link
Reference in a new issue