148 lines
5.2 KiB
Markdown
148 lines
5.2 KiB
Markdown
# 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 16, 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_
|