Softwarearchitektur

Allgemeiner Überblick

Weitere technische Details aller Repositories finden Sie auch unter "Repositories".

Frontend

Das Frontend von Behörden-KlarText besteht aus zwei Microsoft-Word-Add-ins (Word Web Add-in und Word VSTO Add-in) und einem Vue-basierten Frontend, die unterschiedliche technische Plattformen und Bereitstellungsmodelle abdecken. Sie erfüllen dieselbe fachliche Funktion der KI-gestützten Vereinfachung markierter Textpassagen mithilfe von Large Language Models (LLMs).

Die Frontends übernehmen die Benutzerinteraktion, Texterfassung und -anzeige und die Übergabe von Texten zur Verarbeitung. Nicht Bestandteil des Frontends sind die Geschäftslogik, Prompt- und Modellsteuerung, KI- und LLM-Verarbeitung und Persistenz oder Auswertung. Diese Verantwortlichkeiten liegen vollständig im Backend und im LLM-Service.

VSTO Add-in (C#, .NET)

Das VSTO-Add-in ist ein klassisches Desktop-Add-in für Microsoft Word unter Windows und richtet sich an Office-Installationen ab Word 2016. Es ist in C# auf .NET-Basis implementiert und nutzt das native Word-Objektmodell.

Das Add-in zeichnet sich durch folgende architektonische Merkmale und Aufgaben aus: Es wird lokal auf dem Client-System installiert (MSI-basiert) und ermöglicht den direkten Zugriff auf Dokumente sowie Textselektionen über das Word-Objektmodell. Markierte Textpassagen können direkt zur Optimierung übergeben werden. Die optimierten Texte werden anschließend wieder in das Dokument eingefügt.

Das VSTO Add-in eignet sich insbesondere für kontrollierte Desktop-Umgebungen, in denen lokale Installation, feste Backend-Endpunkte und direkte Kommunikation zulässig sind.

Web-Add-in (Office Add-in, manifest.xml)

Das Web-Add-in ist ein webbasiertes Office-Add-in, das über eine manifest.xml in Microsoft Word eingebunden wird. Es richtet sich primär an Microsoft 365 und ist plattformübergreifend einsetzbar. Die Benutzeroberfläche des Add-ins besteht aus HTML- und JavaScript-Komponenten, die auf einem Nginx-Webserver bereitgestellt werden.

Das Add-in ermöglicht die Nutzung in Word Desktop, Word Online und Word für macOS. Die UI wird zentral über den Nginx-Webserver ausgeliefert, während der Zugriff auf Dokumentinhalte über die Office.js-API erfolgt. Die Kommunikation mit dem Backend erfolgt indirekt über den Webserver, wodurch eine zentrale Wartung und Aktualisierung ohne lokale Installation möglich ist.

Das Web-Add-in wurde für skalierbare, wartungsarme und plattformübergreifende Szenarien konzipiert. Es trennt die Auslieferung der Benutzeroberfläche klar von der Backend-Logik. Grundsätzlich ist das Add-in für Microsoft 365 optimiert, eine eingeschränkte Nutzung unter Office 2016 und neueren Versionen ist jedoch ebenfalls möglich. Dabei sind bestimmte Einschränkungen bei Shortcuts oder Anpassungen je nach Office-Version zu beachten, und die Nutzung erfolgt unter Berücksichtigung der Lizenzbedingungen der Office JavaScript API (vgl. Microsoft Office JavaScript API – Lizenz- und Nutzungsbedingungen).

Vue-Frontend (Webanwendung)

Das Vue-Frontend ist eine eigenständige, webbasierte Anwendung, die als Prototyp entwickelt wurde, um schnell und unkompliziert Feedback von Nutzenden zur Qualität der KI-generierten Texte zu sammeln. In Aufbau und Bedienlogik orientiert es sich funktional am Word-Add-in, ist jedoch unabhängig von Microsoft Office nutzbar.

Nutzende können Text direkt im Browser eingeben, ausgewählte Passagen optimieren lassen und im Anschluss gezielt Feedback zur Textqualität geben. Dadurch eignet sich das Vue-Frontend insbesondere für Tests, Pilotierungen und qualitative Evaluationen der LLM-basierten Textvereinfachung.

Die Benutzeroberfläche wird mit dem JavaScript-Framework Vue.js umgesetzt. Die Anwendung läuft vollständig im Browser und wird über einen Webserver (z. B. Nginx) ausgeliefert.

Backend

Das Backend von Behörden-KlarText ist die zentrale Verarbeitungskomponente der Softwarearchitektur.
Es stellt eine API bereit, über die Texte mithilfe verschiedener Large Language Models (LLMs) optimiert werden können, und kapselt die gesamte Verarbeitungslogik.

Das Backend verarbeitet Anfragen aus den Frontends, lädt zur Laufzeit die erforderlichen Secrets für die Authentifizierung gegenüber externen LLM-Diensten und stellt Health-Check-Endpunkte zur Überwachung der Verfügbarkeit bereit.
Über definierte API-Endpunkte können Nutzerinnen und Nutzer optimierte Textfassungen abrufen.

Zusätzlich unterstützt das Backend konfigurierbare Begriffe, die bei der Textoptimierung bewusst ausgespart und nicht verändert werden.

Der Service ist in Python implementiert. Die API basiert auf FastAPI und wird über uvicorn betrieben. Die Qualitätssicherung erfolgt über automatisierte Tests mit pytest.

Durch die klare Trennung von Frontend und LLM-Anbindung ermöglicht das Backend eine flexible Erweiterung, einfache Skalierung und den Austausch von Modellen ohne Auswirkungen auf die Benutzeroberflächen.

LLM Service

Der LLM Service stellt die KI-basierte Textverarbeitung innerhalb der Behörden-KlarText-Architektur bereit.
Er ist für das Hosting und die Ausführung des Sprachmodells verantwortlich und wird vom Backend über definierte Schnittstellen angesprochen.

Das Model Hosting kann beispielsweise über vLLM erfolgen, das eine effiziente und skalierbare Ausführung von Large Language Models ermöglicht.
Zur Optimierung und Vereinfachung von Texten kommen Large Language Models (LLMs) zum Einsatz. Die Architektur ist dabei modellagnostisch ausgelegt; Modelle wie Gemma 3 (27B) dienen lediglich als Beispiel und können je nach Anforderungen ausgetauscht oder ergänzt werden. Dadurch ist ein Deployment sowohl in eigenen Infrastrukturen, als auch bei externen Cloud- oder Anbieter-Services möglich.

Der LLM Service ist als eigenständige Komponente ausgelegt und vom Backend logisch getrennt.
Diese Trennung ermöglicht eine unabhängige Skalierung sowie den Austausch oder die Aktualisierung des Modells und dessen Hostings, wobei ausschließlich Konfigurationsänderungen im Backend oder in den Frontends erforderlich sind.

Infrastruktur / DevOps

Die Infrastruktur- und DevOps‑Umgebung von Behörden-KlarText ist für einen automatisierten, reproduzierbaren und sicheren Betrieb der Gesamtarchitektur ausgelegt. Der folgende Vorschlag umfasst den Betrieb der Frontend‑Add‑ins, des Python‑Backends (FastAPI/Uvicorn) sowie des LLM‑Services, jeweils in containerisierten Umgebungen. Mit den veröffentlichten Repositories wird eine mögliche Konfiguration der CI/CD-Pipelines bereitgestellt. Die Integration in das IT-System muss von Ihrem IT-Dienstleister umgesetzt werden.

Zentrales Element ist eine CI/CD‑Pipeline, die den gesamten Auslieferungsprozess von der Quellcode‑Änderung bis zum Rollout in die Zielumgebung automatisiert. Bausteine sind hierbei:

• Build- und Test‑Stufen, in denen Backend‑ und LLM‑Service‑Container gebaut, mit Tools wie Pytest getestet und auf Sicherheits‑ und Qualitätsanforderungen geprüft werden.
• Eine Container‑Registry zur Verwaltung, Versionierung und Signierung der erzeugten Container‑Images, das als vertrauenswürdige Quelle für Deployments dient.​
• Ein GitOps‑basiertes Deployment (CD-Tool), das den gewünschten Zielzustand der Kubernetes‑ oder OpenShift‑Cluster aus einem Git‑Repository ausliest und kontinuierlich mit dem tatsächlichen Zustand abgleicht.​
• Der Betrieb auf einer Container-Orchestrierungsplattform, die Skalierung, Self‑Healing, Rolling Updates und isolierte Namespaces für Backend, LLM‑Service, Monitoring‑Stack (OpenTelemetry Collector, Prometheus) und ggf. Nginx‑UI bereitstellt.​

Datenfluss

Der Datenfluss in der Behörden-KlarText-Architektur ist klar strukturiert und trennt Frontend, Backend und LLM-Service strikt voneinander. Die typischen Schritte sind:

1. Texterfassung im Frontend:
   Nutzerinnen markieren Textpassagen in Microsoft Word (über das VSTO- oder Web-Add-in) oder im Vue-Frontend. Das jeweilige Add-in bzw. die Webanwendung erfasst die markierten Passagen und bereitet sie für die weitere Verarbeitung vor.

2. Übertragung an das Backend:
   Im Web-Add-in und dem Vue-Frontend werden die Texte zunächst an den Nginx-Webserver geleitet, der die Anfrage weiter an das Backend übergibt.

3. Verarbeitung im Backend:
   Das Backend übernimmt die Validierung der Anfrage, lädt ggf. erforderliche Secrets für LLM-Dienste und wendet konfigurierbare Regeln (z. B. geschützte Begriffe) an. Anschließend wird die Textpassage an den LLM-Service weitergeleitet.

4. Optimierung durch den LLM-Service:
   Der LLM-Service verarbeitet die Texte, vereinfacht sie und liefert eine optimierte Version zurück an das Backend.

5. Rückgabe an das Frontend:
   Das Backend überträgt die optimierten Texte zurück an das Add-in, das die Ergebnisse in das Word-Dokument einfügt.

Durch diese Struktur ist der Datenfluss transparent, nachvollziehbar und sicher, wobei Frontend, Backend und LLM-Service unabhängig voneinander skaliert oder ausgetauscht werden können.