Skip to content
BranchesTags

Repository files navigation

Graphenbasierte Systeme

Ein Full-Stack-Projekt zur Erforschung graphbasierter Analysen mithilfe von Generativer KI. Das System kombiniert eine moderne Chat-Oberfläche, ein intelligentes Backend zur Orchestrierung und einen spezialisierten MCP-Server für den Zugriff auf historische Graphdaten (Neo4j).

Architektur

Das Projekt verfolgt einen Microservices-Ansatz und besteht aus drei Hauptkomponenten:

  1. Frontend (Frontend/):
  • Technologie: Next.js 15 App.
  • Funktion: Bietet die Benutzeroberfläche für den Chat und die Visualisierung von Quellen.
  1. Backend (Backend/):
  • Technologie: NestJS App.
  • Funktion: API-Gateway und Orchestrator. Verwaltet Benutzer & Authentifizierung (JWT), speichert Chat-Verläufe in PostgreSQL und kommuniziert mit dem LLM (Gemini) sowie dem MCP-Server.
  1. MCP Server (MCPServer/):
  • Technologie: Python (FastMCP).
  • Funktion: Stellt die Verbindung zur Neo4j Graphdatenbank her und bietet Tools (read_database, search_nodes_by_text) für das LLM an.

Projektstruktur

.
├─ Backend/             # NestJS App (API Gateway & Orchestrierung)
│  ├─ README.md         # Detaildoku Backend
│  ├─ src/
│  └─ .env              # Konfiguration (DB, Gemini, MCP-URL)
├─ Frontend/            # Next.js 15 App (UI)
│  ├─ README_Frontend.md
│  └─ app/, components/
└─ MCPServer/           # Python MCP Server (Neo4j Tools)
   ├─ src/
   │  └─ server.py
   └─ requirements.txt

Datenbanken

  • Neo4j: Beinhaltet die historischen Graphdaten (Briefe, Personen, Beziehungen).
  • PostgreSQL: Speichert relationale Daten wie Benutzer (User, Hash-Passwörter) und die Chat-Historie.

Features & Authentifizierung

Die Anwendung bietet eine vollständige Benutzerverwaltung. Beim ersten Besuch wirst du zur Login-Seite (/auth) weitergeleitet.

  • Registrieren: Neues Konto mit E-Mail und Passwort erstellen.
  • Anmelden: Login mit bestehendem Konto (JWT Token wird lokal gespeichert).
  • Demo-Login: Schnellzugriff zum Testen ohne Registrierung (User: demo@example.com).

Setup mit Docker (Empfohlen)

Die einfachste Methode, das gesamte System zu starten.

Voraussetzungen

  • Docker & Docker Compose installiert.
  • Zugang zu einer Neo4j Instanz (oder lokale Konfiguration in docker-compose.yml).
  • Optional: Google Gemini API Key (für Online-Modell).

Production Mode (Optimiert & schnell)

# Komplettes System im Production-Mode starten
docker-compose up --build

Dies startet alle Services optimiert für Production:

  • ✅ Optimierte Builds (Frontend & Backend)
  • ✅ Schnellerer Start nach erstem Build
  • ✅ Keine Hot-Reload / File-Watching
  • ⚠️ Code-Änderungen erfordern Rebuild

Services:

  • PostgreSQL Container (Port 5435)
  • MCP Server (Port 8000)
  • Backend (Port 8083) - Production Build
  • Frontend (Port 3000) - Optimierter Next.js Build

Die Web-App ist dann unter http://localhost:3000 erreichbar.

Development Mode (Hot Reload)

Für aktive Entwicklung mit automatischem Neuladen bei Code-Änderungen:

# Development-Modus mit Hot-Reload
docker-compose -f docker-compose.dev.yml up --build

Vorteile:

  • ✅ Automatisches Neuladen bei Dateiänderungen
  • ✅ Schnellere Iteration während Entwicklung
  • ✅ Live TypeScript-Compilation
  • ⚠️ Langsamere Performance als Production

Einzelne Services neu starten

# Nur Backend neu bauen
docker-compose up --build backend

# Nur Frontend neu bauen
docker-compose up --build frontend

# Services stoppen
docker-compose down

# Services stoppen + Volumes löschen (Datenbank-Reset)
docker-compose down -v

Konfiguration

Docker Compose (Standard)

Alle notwendigen Konfigurationen sind bereits in docker-compose.yml enthalten!

Für produktive Umgebungen solltest du nur folgende Werte anpassen:

Backend Environment Variables:

environment:
  DB_PASS: your_secure_password        # ⚠️ Ändern!
  JWT_SECRET: your_secure_jwt_secret   # ⚠️ Ändern!

MCP Server Environment Variables:

environment:
  NEO4J_URI: neo4j+ssc://your-neo4j-host:7687
  NEO4J_PASSWORD: your_neo4j_password  # ⚠️ Ändern!

Optionale Backend .env (nicht erforderlich)

Falls du Werte überschreiben möchtest, erstelle Backend/.env:

# Backend/.env (OPTIONAL - überschreibt docker-compose Werte)

# Gemini API Key für Online-Modell
GEMINI_API_KEY=AIzaSy...

# Request Logging für Debugging
ENABLE_FILE_LOGGING=true

Hinweis: Siehe Backend/.env.example für Template.

Frontend-Konfiguration

Das Frontend benötigt nur eine Variable, die in docker-compose.yml bereits gesetzt ist:

environment:
  NEXT_PUBLIC_API_BASE_URL: http://localhost:8083

Container Management

Logs anzeigen

# Alle Container Logs
docker-compose logs -f

# Nur Backend
docker-compose logs -f backend

# Nur Frontend
docker-compose logs -f frontend

Container Status prüfen

# Status aller Container
docker-compose ps

# Ressourcen-Nutzung
docker stats graph_backend graph_frontend sozinianer-mcp

In Container einsteigen (Debugging)

# Backend Container Shell
docker exec -it graph_backend sh

# Frontend Container Shell
docker exec -it graph_frontend sh

# Datenbank Shell
docker exec -it graph_project_postgres psql -U postgres -d graph_project

Datenbank zurücksetzen

# Alle Volumes löschen (inkl. Datenbank)
docker-compose down -v

# Neu starten
docker-compose up --build

Detaillierte Dokumentation

Für spezifische Themen siehe:

Entwicklung

Code-Änderungen

Production Mode (Standard):

# 1. Code ändern
# 2. Container neu bauen
docker-compose up --build backend  # oder frontend

Development Mode (schnellere Iteration):

# Hot Reload aktiviert - keine Rebuilds nötig
docker-compose -f docker-compose.dev.yml up

Tests ausführen

# Backend Tests
docker exec -it graph_backend pnpm test

# Frontend Tests  
docker exec -it graph_frontend pnpm test

Troubleshooting

Fehler "No valid session ID provided" beim Erstellen neuer Chats

Ursache: Race Condition zwischen Session-Erstellung und Assistant-Aufruf.

Lösung: Dieser Fehler wurde behoben (v1.1.0). Die Session wird jetzt vollständig im Backend gespeichert, bevor der Assistant aufgerufen wird. Falls der Fehler weiterhin auftritt:

  1. Cache leeren (Strg+Shift+R)
  2. Prüfe ob Backend und Frontend auf dem gleichen Stand sind
  3. Überprüfe die Browser-Konsole auf zusätzliche Fehler

Browser-Console zeigt viele Fehler von "content_script.js"

Ursache: Browser-Extensions (z.B. Avast, Bitdefender) interferieren mit React's DOM-Manipulation.

Lösung:

  1. Deaktiviere temporär Antivirus/Security-Extensions während der Entwicklung
  2. Die Fehler beeinflussen nicht die Funktionalität der App
  3. In Production-Builds sind diese Fehler weniger sichtbar

MCP Server / Backend startet nicht

Siehe ausführliche Debugging-Anleitung:

Nützliche Ressourcen

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages