Synaplan Multimodal Gateway

Synaplan

KI-gestütztes Wissensmanagement mit RAG, Chat-Widgets und Multi-Channel-Integration.

Live-Instanz: web.synaplan.com  |  Dokumentation: docs.synaplan.com  |  API: Swagger UI

---

Voraussetzungen

• Docker + Docker Compose v2 (Docker Desktop unter macOS/Windows oder Docker Engine + das Compose-Plugin unter Linux)
• Git
• 8 GB RAM Minimum (16 GB empfohlen für die Standardinstallation mit lokaler KI)
• ~9 GB freier Speicherplatz für die Standardinstallation (~5 GB für Minimal)
• Freie TCP-Ports 5173, 8000, 8082, 8025, 3307, 6333, 11435

Apple Silicon (M1–M4) Macs: Synaplans Container-Images werden für linux/amd64 veröffentlicht und laufen daher unter Emulation auf Apple Silicon. Aktivieren Sie in Docker Desktop → Einstellungen → Allgemein die Option „Rosetta für x86/amd64-Emulation auf Apple Silicon verwenden“ (macOS 13+), um deutlich schnellere und stabilere Container als mit dem standardmäßigen QEMU zu erhalten. Ohne diese Einstellung funktioniert alles – nur langsamer, und der erste Build dauert länger.

Schnellstart

git clone https://github.com/metadist/synaplan.git
cd synaplan
docker compose up -d

Öffnen Sie http://localhost:5173 — die Benutzeroberfläche ist in ca. 2 Minuten bereit. Bei der Standardinstallation werden lokale Ollama-Modelle (gpt-oss:20b, bge-m3, insgesamt ~14 GB) im Hintergrund weiter heruntergeladen – Chats, die lokale KI nutzen, funktionieren, sobald der Download abgeschlossen ist (docker compose logs -f backend zeigt den Fortschritt an). Für das schnellste erste Erlebnis verwenden Sie die unten beschriebene Minimal-Installation.

---

Installationsoptionen

Modus	Befehl	Größe	Am besten geeignet für
Standard	docker compose up -d	~9 GB	Voller Funktionsumfang, lokale KI
Minimal	docker compose -f docker-compose-minimal.yml up -d	~5 GB	Nur Cloud-KI (Groq/OpenAI)

Setzen Sie für die Minimalinstallation Ihren API-Schlüssel vor dem Start des Stacks, damit er beim ersten Start bereits erkannt wird (vermeidet einen Neustart). Einen kostenlosen Schlüssel erhalten Sie unter console.groq.com:

echo "GROQ_API_KEY=your_key" >> backend/.env
docker compose -f docker-compose-minimal.yml up -d

Bereits ohne Schlüssel gestartet? Fügen Sie ihn hinzu und starten Sie das Backend neu:

echo "GROQ_API_KEY=your_key" >> backend/.env && docker compose restart backend

---

Zugriff

Dienst	URL
App	http://localhost:5173
API	http://localhost:8000
API-Dokumentation	http://localhost:8000/api/doc
phpMyAdmin	http://localhost:8082
MailHog	http://localhost:8025

Standard-Anmeldedaten:

E-Mail	Passwort	Stufe
[email protected]	admin123	ADMIN
[email protected]	demo123	PRO
[email protected]	test123	NEU (unbestätigt)

---

Funktionen

• KI-Chat — Ollama, OpenAI, Anthropic, Groq, Gemini
• Multi-Task-Routing — Ein KI-Planer zerlegt komplexe Anfragen in einen Aufgabengraphen (extrahieren → zusammenfassen → generieren → antworten) und streamt Live-Aufgabenkarten, während die Schritte ausgeführt werden
• RAG-Suche — Semantische Dokumentensuche mit MariaDB VECTOR oder Qdrant
• Chat-Widget — Auf jeder Website einbinden (Widget-Anleitung)
• Live-Support — Echtzeit-WebSocket-Schicht (Centrifugo + Redis): menschliche Übernahme von Widget-Chats, Tippindikatoren, Operator-Benachrichtigungen (Echtzeit-Anleitung)
• WhatsApp — Integration der Meta Business API
• E-Mail — KI-gestützte E-Mail-Antworten
• Audio — Whisper-Transkription (Eingabe) + optionales synaplan-tts (Ausgabe)
• Dokumente — PDF, Word, Excel, Bilder mit OCR
• KI-Erinnerungen — Benutzerprofilierung mit Qdrant-Vektorsuche
• Feedback-System — Erfassung und Analyse von Feedback, unterstützt durch Qdrant
• Plugins — Nicht-invasives Plugin-System (Plugin-Anleitung)
• MCP-Server (Early Access) — Verbinden Sie KI-Clients (Claude, Cursor, …) über das Model Context Protocol; Ihre RAG und Erinnerungen werden zu Werkzeugen unter POST /mcp (MCP-Anleitung)
• MCP-Client (Early Access) — Binden Sie Ihre MCP-Server (CRM, Wiki, n8n, …) unter Kanäle → MCP-Server ein; der Multi-Task-Planer bezieht Live-Daten von ihnen über mcp_fetch DAG-Knoten — schreibgeschützt, SSRF-geschützt, pro Thema aktivierbar. Ermöglicht durch gesetzte BCONFIG-Flags (MCP.CLIENT_ENABLED, MULTITASK.MCP_FETCH_ENABLED — app:seed setzt sie beim Deployment auf EIN; eine explizite 0-Zeile dient als Notausschalter für den Operator). Siehe docs/MULTITASK_DATA_NODES.md

---

Qdrant-Vektordatenbank

Qdrant läuft als interner Docker-Dienst — keine Konfiguration erforderlich. Es unterstützt KI-Erinnerungen, die RAG-Dokumentensuche und das Feedback-System.

Startet automatisch mit docker compose up -d. Synaplan funktioniert vollständig ohne (Erinnerungen und Vektorsuche sind dann deaktiviert).

---

Echtzeit & Hintergrundverarbeitung

Beide Compose-Dateien starten außerdem drei interne Dienste (keine Host-Ports, keine Einrichtung erforderlich):

Dienst	Rolle
redis	Obligatorische gemeinsame Infrastruktur: Cache, Sitzungen, Sperren, Ratenbegrenzung, Nachrichtenwarteschlangen (Redis Streams), Centrifugo-Engine
centrifugo	WebSocket-Gateway für Echtzeitfunktionen (Live-Chat-Übernahme, Tippindikatoren, Operator-Benachrichtigungen) — Browser verbinden sich same-origin über /connection/websocket
worker	Symfony Messenger Consumer, der asynchrone Jobs ausführt (KI-Verarbeitung, Dokumentenindizierung, Widget-Crawling)

In einem Multi-Node-Cluster teilen sich alle Nodes ein Redis, sodass WebSocket-Ereignisse, die auf einem Node veröffentlicht werden, Browser erreichen, die mit einem beliebigen anderen verbunden sind. Details: docs/REALTIME.md.

---

Text-to-Speech (Optional)

Für Sprachausgabe führen Sie synaplan-tts parallel zu Synaplan aus:

git clone https://github.com/metadist/synaplan-tts.git && cd synaplan-tts && docker compose up -d

---

Häufige Befehle

# Logs
docker compose logs -f backend

# Restart
docker compose restart backend

# Reset database
docker compose down -v && docker compose up -d

# Run tests
make test

# Code quality
make lint

---

Dokumentation

Benutzer- und API-Dokumentation finden Sie unter docs.synaplan.com. Quelle: metadist/synaplan-docs.

Interne Anleitungen (für Entwickler, die an dieser Codebasis arbeiten):

Anleitung	Beschreibung
Installation	Detaillierte Einrichtungsanweisungen
Konfiguration	Umgebungsvariablen, API-Schlüssel
Entwicklung	Befehle, Tests, Architektur
Echtzeit / WebSockets	Centrifugo + Redis Echtzeitschicht, Multi-Node-Bereitstellung
RAG-System	Dokumentensuche und -verarbeitung
Chat-Widget	Chat auf Websites einbetten
WhatsApp	Einrichtung der Meta Business API
E-Mail	E-Mail-Kanal-Integration

Verwandte Repositories

Repository	Zweck
synaplan	Hauptanwendung (dieses Repository)
synaplan-docs	Öffentliche Dokumentationsseite (docs.synaplan.com)
synaplan-tts	Optionaler Piper TTS-Dienst
synaplan-sortx	Plugin zur Dokumentensortierung + lokales Werkzeug
synaplan-charts	Helm-Charts für Kubernetes
synaplan-platform	Konfigurationen für Produktionsbereitstellung

---

Projektstruktur

synaplan/
├── backend/        # Symfony PHP API
├── frontend/       # Vue.js SPA
├── docs/           # Documentation
├── _docker/        # Docker configs
└── plugins/        # Plugin system

---

Mitwirken

Siehe AGENTS.md für Entwicklungsrichtlinien und Codestandards.

---

Lizenz

Apache-2.0