Architektur¶

Plone-Migration ist als containerisierte Webanwendung mit klar getrennten Verantwortungsbereichen aufgebaut. Eine UI-Schicht bedient das Browser-Frontend, eine Domänenschicht verarbeitet Plone-Daten und erzeugt strukturierte Markdown-Repräsentationen, eine API-Schicht kapselt die Anbindung an die externe LLM-Schnittstelle, und eine Export-Schicht erzeugt Markdown- und Word-Dokumente. Die Verarbeitung läuft synchron pro Anfrage; längere Operationen werden mit Fortschrittsmeldungen unterlegt. Das Deployment erfolgt als Docker-Container hinter einem Reverse Proxy.

Auf einen Blick¶

Vier-Schichten-Aufbau: UI, Domänenlogik (Plone-Verarbeitung), LLM-API-Anbindung, Export
Sequentielle, zweistufige LLM-Verarbeitung: Inhaltsanalyse → Überarbeitungsvorschläge mit Analyse als Kontext
Externe Anbindung ausschließlich über eine OpenAI-kompatible Chat-Completions-API
In-Memory-Verarbeitung mit temporären Dateien für Downloads; kein persistenter Speicher
Containerbetrieb (Docker) hinter Reverse Proxy mit konfigurierbarem Root-Pfad
Konfiguration vollständig über Umgebungsvariablen (Endpunkt, Modell, Timeouts, Server-Bindung)
Optionale Komponenten (Word-Export) mit Graceful-Degradation-Mechanik

Komponenten und Workflow¶

Die Verarbeitung folgt einem linearen Datenfluss vom Datei-Upload über die Strukturierung bis zur LLM-gestützten Aufbereitung und dem Export. Jede Stufe hinterlegt ihre Ergebnisse in einem internen Zustand, sodass nachgelagerte Schritte (z. B. mehrere Exportformate) ohne erneute Verarbeitung möglich sind.

flowchart TB
  Browser[Browser]

  subgraph App[Anwendungscontainer]
    UI[UI-Schicht<br/>Gradio Blocks]
    Domain[Domänenlogik<br/>Plone-Parser, Hierarchie, Markdown-Erzeugung]
    LLMClient[LLM-Client<br/>Retry, Timeout, Chunking]
    Exporter[Export-Schicht<br/>Markdown, ZIP, Word]
    State[(In-Memory-Zustand<br/>Seiten, Hierarchie, Ergebnisse)]
  end

  LLM[OpenAI-kompatible<br/>LLM-API]
  Files[(Temporäre<br/>Download-Dateien)]

  Browser -- HTTP/Reverse Proxy --> UI
  UI --> Domain
  Domain --> State
  State --> Exporter
  UI --> LLMClient
  LLMClient -- Chat Completions --> LLM
  LLM -- Antwort --> LLMClient
  LLMClient --> State
  Exporter --> Files
  Files --> UI
  UI --> Browser

UI-Schicht¶

Die UI ist mit einem Webframework realisiert, das Eingabefelder, Buttons, Dateiausgaben und Markdown-Vorschauen direkt im Browser bereitstellt. Sie reicht Eingaben an die Domänenlogik weiter und stellt Zwischenergebnisse aus dem Anwendungszustand dar. Längere Vorgänge werden über einen Fortschritts-Callback in der Oberfläche signalisiert.

Domänenschicht (Plone-Verarbeitung)¶

Die Domänenschicht parst den hochgeladenen Plone-JSON-Export, normalisiert Felder und baut die Seitenhierarchie über die Plone-UIDs auf. Aus den HTML-Inhalten der Seiten wird ein vereinheitlichtes Markdown erzeugt; eingebettete Base64-Bilder werden durch Platzhalter ersetzt. Die Schicht stellt sowohl eine konsolidierte Gesamtansicht als auch seitenweise Repräsentationen bereit. Pfade und Dateinamen werden für plattformübergreifende Nutzung bereinigt (Umlaut-Ersetzung, Längenbegrenzung, Konfliktauflösung über Suffixe).

LLM-Anbindung¶

Der LLM-Client kapselt die Kommunikation mit der externen Chat-Completions-API. Er hält für jede Stufe einen eigenen Prompt vor (Inhaltsanalyse, Überarbeitungsvorschläge) und führt zwei sequentielle Aufrufe aus: Im ersten Aufruf wird das Markdown analysiert; im zweiten Aufruf wird das Analyse-Ergebnis als Kontext gemeinsam mit den Originalinhalten an das Modell zurückgegeben, um konkrete Überarbeitungsvorschläge zu erzeugen. Sehr umfangreiche Inhalte werden vor dem Versand gekürzt; ein Hilfsdienst zur Aufteilung in Chunks steht für künftige Erweiterungen bereit. Bei vorübergehenden Fehlern (HTTP 429, Timeouts, Verbindungsabbrüche) werden die Anfragen mit exponentiellem Backoff bis zu einer konfigurierbaren Anzahl von Versuchen wiederholt.

Export-Schicht¶

Die Export-Schicht erzeugt aus dem Anwendungszustand die nutzerseitig herunterladbaren Artefakte. Markdown-Exporte werden direkt aus dem zwischengespeicherten Inhalt erstellt; ZIP-Exporte spiegeln die Plone-Hierarchie als Verzeichnisbaum und ergänzen eine _structure.md mit Übersichten und Statistiken. Der Word-Export ist optional: Bei verfügbarer Abhängigkeit entstehen .docx-Dateien mit gesetzten Metadaten; fehlt die Abhängigkeit, bleibt der Markdown-Pfad ungestört nutzbar. Alle Ergebnisdateien werden in temporären Verzeichnissen abgelegt und vom Webframework verwaltet.

Zustandshaltung und Nebenläufigkeit¶

Verarbeitete Seiten, die rekonstruierte Hierarchie, der aggregierte Markdown-Inhalt sowie die zuletzt erzeugten LLM-Ergebnisse werden in einem prozesslokalen Zustand gehalten. Persistierung über die Laufzeit eines Containers hinaus ist nicht vorgesehen; ein Neustart leert den Zustand. Die Verarbeitung erfolgt pro Anfrage synchron, ist aber durch das Framework so eingebettet, dass die UI während längerer Operationen weiterhin Statusmeldungen empfängt.

Konfiguration und Deployment¶

Die Anwendung wird als Docker-Container betrieben. Build- und Laufzeitparameter (LLM-Endpunkt, Modellname, API-Schlüssel, Timeout, Wiederholungsversuche, Server-Bindung, Root-Pfad) werden über Umgebungsvariablen gesetzt. Für den Betrieb hinter einem Reverse Proxy ist eine Beispielkonfiguration für Nginx hinterlegt, die unter anderem das Upload-Limit auf 100 MB anhebt und WebSocket-Upgrades für die Live-Aktualisierung der UI durchreicht.

Robustheit¶

Robustheit wird auf mehreren Ebenen adressiert: Wiederholungsversuche mit exponentiellem Backoff in der LLM-Anbindung, Bereinigung und Längenbegrenzung von Pfaden, Konfliktauflösung bei doppelten Dateinamen, Trunkierung überlanger Eingaben mit Hinweismeldung sowie Graceful Degradation für optionale Komponenten.

Technologie-Übersicht¶

Sprache und Laufzeit: Python 3.13
Webframework: Gradio (UI, Datei-Handling, Fortschritts-Callbacks)
HTTP-Client: requests
Dokumenterzeugung: python-docx (Word), BeautifulSoup4 und lxml (HTML-Parsing)
Externe Schnittstelle: OpenAI-kompatible Chat-Completions-API
Containerisierung: Docker, Docker Compose
Reverse Proxy: Nginx (Beispielkonfiguration mitgeliefert)