Files
tsumugu/docs/architecture/Tsumugu_Connector_Suite_Architektur_v0.2.md
LarsandCursor d6b70d8f92
Deploy Development / deploy (push) Successful in 28s
Test Suite / pytest-backend (push) Failing after 2m18s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 10s
Schließe die Connector-Kapselung ab, damit Paperless, IMAP und weitere Quellen über dieselbe Anbindung laufen.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-19 15:00:50 +02:00

31 KiB
Raw Permalink Blame History

Tsumugu – Connector Suite: Architekturkonzept

Version: 0.2 · Stand: 19.10.2026
Status: Konsolidierter fachlich-technischer Konzeptstand, keine Implementierungsfreigabe
Geltungsbereich: Tsumugu; mögliche spätere Wiederverwendung in Jinkendo nach gesonderter Prüfung
Grundlage: Fortgeschriebene Festlegungen in dieser Unterhaltung vom 18.–19.10.2026 und Tsumugu_Product_Recovery_Baseline_v0.1.md (16.10.2026).

1. Zielbild und Abgrenzung

Tsumugu ist ein universeller Vorgangs-, Akten- und Informationsmanager. Es führt Ressourcen und Informationen zu Vorgängen zusammen, ohne die angeschlossenen Systeme zu ersetzen. Aktenstruktur, Beziehungen, Notizen, Aufgaben, Fristen, Chronologie und fachliche Zuordnungen sind Tsumugu-eigene Informationen. Dokumente, E-Mails, Dateien und Bankbuchungen verbleiben grundsätzlich in ihren Quellen.

Die Connector Suite erschließt externe Ressourcen und Dienste über eine einheitliche Integrationsarchitektur. Sie ermöglicht Navigation, Suche, Lesen, Metadaten, Darstellung, bei geeigneter Quelle Bearbeitung und selektive Aktualisierung. Sie ist keine generelle Import-, Spiegelungs- oder Archivierungsplattform.

Geschäftliches Ziel: Dasselbe Produkt soll sowohl vollständig selbst gehostet als auch als SaaS mit kundenseitig betriebener Connector Runtime angeboten werden können. Eine SaaS-Variante mit zentralen Connectoren bleibt möglich. Self-Hosting ist insbesondere für datenschutz- und selbsthostingaffine Paperless-Nutzer relevant. Die kommerzielle Nachfrage ist eine Hypothese, keine nachgewiesene Tatsache.

Leitprinzipien:

  • Source of Truth: Externe Quelldaten bleiben im jeweiligen führenden System.
  • Reference first: Tsumugu speichert primär Referenzen, eigene Fachdaten und nötige, freigegebene Metadaten.
  • Least privilege: Rechte aus Quellsystem und Tsumugu gelten gemeinsam.
  • Policy-based placement: Pro Connector-Instanz und Datenklasse bestimmen, was gespeichert, übertragen oder verarbeitet werden darf. Lokale Speicherung ist eine Option, keine pauschale Pflicht.
  • Cloud content opt-out: SaaS-Kunden können die dauerhafte Cloud-Speicherung von Dokumentinhalten und KI-Artefakten vollständig deaktivieren.
  • Capability based: Verschiedene Connectoren bieten verschiedene Operationen, Ressourcentypen und Darstellungsarten an.
  • Pragmatic UI: Generische Tsumugu-Komponenten vor beliebig ladbarem Connector-Frontend-Code.
  • Demand driven: Keine allgemeine Plattformkomplexität oder zusätzliche Blueprints ohne konkreten Modulbedarf.

2. Logische Gesamtarchitektur

             ┌──────────────────────────────────────────────┐
             │ Tsumugu UI                                  │
             │ Akten | Ressourcenbrowser | Suche | Preview  │
             │ Metadatenansicht/-editor | Aufgaben/Fristen  │
             └───────────────────┬──────────────────────────┘
                                 │ standardisierte Ressourcen-/UI-Verträge
             ┌───────────────────▼──────────────────────────┐
             │ Tsumugu Core                                │
             │ Akten, Links, Notizen, Metadatenindex,       │
             │ CollectionBindings, Rechte, Daten-Policies  │
             └───────────────────┬──────────────────────────┘
                                 │ autorisierte Connector-Operationen
             ┌───────────────────▼──────────────────────────┐
             │ Connector Runtime / Adapter                 │
             │ Fähigkeiten, Quellzugang, Mapping, Sync,     │
             │ Export, Zugriffskontrolle, lokale Ablage     │
             └─────┬──────────┬──────────┬───────────┬─────┘
                   │          │          │           │
               Paperless     IMAP     Dateien      Bank/API
                                       │
                                  Lokales NAS
                        Processing-Dienste (z.B. KI) als
                          eigener Fähigkeitsvertrag

Betriebsformen

A – Self-Hosted: Tsumugu Core und Connector Runtime laufen in einer selbst betriebenen Umgebung, gegebenenfalls auf separaten lokalen Systemen.

B – Hybrid-SaaS (bevorzugte Zielrichtung): Tsumugu Core läuft beim Anbieter, die Connector Runtime optional beim Kunden. Sie verbindet lokale/zugängliche Quellsysteme und setzt Datenfreigaben durch. Tsumugu persistiert nur freigegebene Referenzen/Metadaten und eigene Fachdaten. Originaldokumente müssen nicht im SaaS-Speicher liegen.

C – SaaS mit zentralen Connectoren: Für Nutzer ohne lokale Infrastruktur grundsätzlich möglich, aber nicht als Voraussetzung für die erste Umsetzung.

Grenze: Eine lokale Runtime schützt Daten nicht automatisch vor Cloud-Übertragung. Vorschau, Live-Suche, KI-Anfragen, Protokolle und temporäre Verarbeitung unterliegen ebenfalls einer expliziten Datenfluss-Policy. Der sichere Kommunikationskanal (Initiierung, Authentisierung, Autorisierung, Verbindungsausfall) ist noch technisch auszugestalten.

3. Connector-Kategorien

Kategorie Wesentliche Aufgabe Erste Anwendungsfälle Architektonische Einordnung
Source Datenbestand navigieren, suchen, lesen, optional bearbeiten Paperless, IMAP, Dateien Gemeinsamer Ressourcenkontrakt
Financial Buchungen und Kontoinformationen strukturiert lesen Banken / Kontoinformationsanbieter Spezialisierte Source-Fähigkeiten, zunächst read-only
Processing Inhalte auswerten und strukturierte Ergebnisse erzeugen KI, perspektivisch OCR/Konvertierung Kein gewöhnlicher Ressourcenbrowser; eigener Eingabe-/Ergebnisvertrag
Storage Konfiguriert ablegen und wiederfinden NAS-/Dateiablage, .eml-Archiv Eigener Ablage-/Abrufvertrag; kann Infrastruktur mit Datei-Source teilen

Die vier Kategorien sind Ordnungsbegriffe, keine Verpflichtung zu vier separaten Servern, Frameworks oder vollständigen APIs. Gemeinsamkeiten werden nur dort standardisiert, wo sie bereits benötigt werden.

3.1 Source: Paperless

  • Vollständige Suche/Navigation im durch Quellidentität berechtigten Bestand, nicht nur in bereits aktenverknüpften Elementen.
  • Dokumentreferenz, Quelle, Metadaten, OCR-/Textabruf auf Anfrage, Original-/Vorschauzugriff.
  • Bearbeitung führender Paperless-Metadaten über Paperless, wenn Connector- und Quellrechte dies erlauben; Tsumugu-eigene Felder separat.
  • Selektiver Metadatenindex, nicht generelle Dokument-/Volltextreplikation.
  • Navigation etwa über Dokumenttypen, Korrespondenten und Tags; konkrete UI-Komponenten noch zu spezifizieren.

3.2 Source: IMAP

  • Postfächer und Ordner navigieren, Nachrichten suchen, Header, Inhalt und Anhänge zugänglich machen.
  • Explizite Einzelreferenzen bleiben bei Ordnerwechsel als Aktenverknüpfung bestehen. IMAP-UID ist typischerweise ordnerbezogen; der Adapter braucht eine belastbare Wiedererkennungsstrategie bzw. meldet nicht auflösbare Referenzen, ohne sie zu löschen.
  • Ordner können als dynamische Sammlung referenziert werden, auch für künftige passende Nachrichten.
  • Optionales lokales .eml-Archiv, Details in Abschnitt 7.
  • Umfang einer vollständigen E-Mail-Bearbeitung (Versenden, Verschieben etc.) ist nicht festgelegt und kein Grund für eine komplette E-Mail-Client-Nachbildung.

3.3 Source: Dateien

  • Zugriff auf explizit freigegebene Verzeichnisse / Netzlaufwerke, Navigation, Suche, Lesezugriff, Vorschau, Metadaten.
  • Pfad und Ressource nach Möglichkeit getrennt modellieren; Verschieben/Umbenennen darf nicht ungeprüft Aktenverknüpfungen löschen.
  • Schreiboperationen nur bei ausdrücklicher Fähigkeit und Berechtigung.

3.4 Financial: Banken (beschlossenes Grundmodell)

  • Financial ist technisch eine spezialisierte Source-Integration, keine eigene Banking-Plattform.
  • Es werden bestehende Banking-/Kontoinformationsdienste integriert; zu Beginn ausschließlich lesender Zugriff auf Einzelbuchungen. Keine Überweisungen oder Zahlungsinitiierung.
  • Vollständige Abfrage des freigegebenen Buchungsbestands ist möglich; Tsumugu speichert standardmäßig keine komplette Umsatzhistorie.
  • Dauerhaft verbleiben insbesondere explizit zugeordnete Buchungsreferenzen und die für Rechnung, Zahlung, Teilzahlung, Sammelzahlung oder Erstattung benötigten Metadaten (etwa Betrag, Datum, Gegenpartei, Verwendungszweck), sofern durch die Datenrichtlinie freigegeben.
  • Rechnungs-/Zahlungszuordnungen sind Tsumugu-eigene Viele-zu-viele-Beziehungen und bleiben auch erhalten, wenn der Banking-Anbieter eine frühere Buchung nicht mehr abrufen kann.
  • Providerwahl, konkrete Einwilligungs-/Zugangsmechanik und Buchungsidentitäten sind integrationsbezogene Umsetzungsfragen.

3.5 Processing / KI (beschlossenes Grundmodell)

  • Processing Connectoren sind Verarbeitungsdienste, keine normale Ressourcenquelle; eigener Eingabe-/Ergebnisvertrag statt erzwungenem Source-Interface.
  • Wesentliche fachliche Fähigkeiten: Extraktion, Klassifikation, Zusammenfassung, informationsgestützte Fragen, Beziehungsanalyse und Handlungsvorschläge. Diese Fähigkeiten sind Aufgabenarten, nicht zwingend eigenständige APIs.
  • Eingaben können Text, strukturierte Daten, Bilder und PDF-Dokumente sein. Moderne multimodale APIs bzw. lokale Modelle können Original-PDFs/Fotos interpretieren; ein separater OCR-Dienst ist optional, keine Pflicht. Vorhandene Paperless-OCR-Texte sollen bei Eignung bevorzugt wiederverwendet werden.
  • Ausführung lokal oder extern entsprechend Datenfreigabe, unterstützter Modellfähigkeit und geeigneter Kosten-/Leistungsabwägung.
  • Verarbeitungsschritte dürfen kombinierbar sein. Keine neue umfassende KI-Agenten- oder Workflow-Plattform als Voraussetzung; bestehende Jinkendo-KI-Gateway-/Workflow-Blueprints bei konkret benötigten Modulen prüfen.
  • Ergebnisse umfassen nachvollziehbare Quellreferenz, Quellstand, Verarbeitungsart und Prüfstatus. Vorschläge (insbesondere Fristen und finanzielle Aussagen) werden nicht ungeprüft zu bestätigten Fakten oder automatischen Aktionen.
  • Wiederverwendbare Ergebnisse können persistiert werden; reine Zwischenstände werden gelöscht. Speicherort nach Datenrichtlinie, nicht generell lokal.
  • Die Freigabe zur temporären externen Verarbeitung ist ausdrücklich getrennt von der Freigabe zur dauerhaften Cloud-Speicherung.
  • Konkrete priorisierte KI-Use-Cases bleiben Produktentscheidungen; Beispiele begründen noch keine umfassende Workflow-Engine.

3.6 Storage (erweiterter Fähigkeitenbereich)

  • Storage dient der konfigurierbaren, sicheren Ablage und dem autorisierten Abruf von Artefakten: z.B. .eml-Archivkopien, strukturierte KI-Extraktionen, Zusammenfassungen, OCR-Volltexte oder temporäre Verarbeitungsdateien.
  • Storage ist kein eigenes DMS, keine Pflichtspiegelung aller Quelldaten und keine Wissens- oder Workflow-Engine.
  • Physische Speicherdienste können lokal (z.B. NAS, Dateisystem, objektbasierter Speicher) oder zentral bereitgestellt werden, soweit Datenrichtlinien dies zulassen.
  • Fachliche Zuordnung, Herkunft und Prüfstatus verwaltet Tsumugu als Result Management; die Storage-Schicht verwaltet Ablage, Abruf, Integrität, Lebensdauer und Löschanforderungen. Result Management ist zunächst eine logische Funktion, kein neuer Pflicht-Microservice.
  • Sonderregel IMAP bleibt bestehen: Aktivierte .eml-Archivkopien liegen nur an einem konfigurierbaren lokalen Ablageort, auch bei SaaS-Nutzung.

4. Ressourcen- und Referenzmodell

Logische Konzepte – kein endgültiges Datenbankschema:

Konzept Bedeutung
Resource Tsumugu-interne stabile Identität eines referenzierten fachlichen Elements
ResourceLocator Einer von mehreren Zugriffswegen zur Ressource (z.B. IMAP-Original, NAS-Archivkopie)
ResourceMetadata Quellmetadaten, normalisierte Suchfelder und Herkunft; Tsumugu-eigene Metadaten fachlich getrennt
CollectionBinding Referenz auf Container/gespeicherte Abfrage mit Zuordnung zu einer Akte und dynamischer Mitgliedschaft
ConnectorInstance Konkrete konfigurierte Verbindung samt Identität, Fähigkeiten und Datenrichtlinien
DataPolicy Erlaubte Speicherung, Übertragung und Verarbeitung je Datenklasse/Connector-Instanz

Ressourcen-Lebenszyklus: Eine live entdeckte Ressource muss nicht automatisch dauerhaft gespeichert werden. Eine explizit zugeordnete Ressource erhält eine stabile Referenz. Ressourcen können zusätzlich durch ausdrücklich konfigurierte Indexierung aufgenommen werden.

Identität und Kopie: IMAP-Original und gesicherte .eml-Kopie können mehrere Locator derselben Tsumugu-Ressource sein. Ein E-Mail-Anhang, der separat in Paperless eingegangen ist, ist grundsätzlich eine eigene, möglicherweise verknüpfte Ressource, nicht automatisch identisch. Ähnliche Inhalte werden nicht ungeprüft zusammengelegt.

Änderungen: Externe Pfade sind nicht notwendigerweise stabile IDs. Bei fehlendem Original bleibt die Aktenreferenz erhalten und zeigt einen differenzierten Auflösungs-/Verfügbarkeitsstatus; wo vorhanden wird eine autorisierte alternative Repräsentation genutzt.

5. Aktenzuordnung und dynamische Sammlungen

Festgelegt sind drei Grundfälle:

  1. Einzelreferenz: bewusstes, dauerhaftes Verknüpfen einer Ressource mit einer oder mehreren Akten; bei Quellverschiebung bleibt die Verknüpfung bestehen.
  2. Statische Auswahl: aktuell ausgewählte Elemente werden einzeln referenziert; sie sind unabhängig von späterer Sammlungsmitgliedschaft.
  3. Dynamische Sammlung: Ordner, Sammlungen oder geeignete gespeicherte Suchregeln können Akten zugeordnet werden. Aktuelle und später hinzukommende passende Ressourcen werden dynamisch angezeigt, ohne Originaldaten zu importieren.

Wichtige Abgrenzung: Eine dynamische Sammlung erzeugt nicht zwingend dauerhafte Einzelreferenzen. Explizite Einzelreferenzen bleiben auch dann erhalten, wenn eine Ressource die Sammlung verlässt. Automatische KI-Bearbeitung/Fristauslösung wird daraus nicht abgeleitet.

Noch offen: Ob einzelne CollectionBindings bei Verlassen der Sammlung optional ein dauerhaftes Referenzieren aller bisherigen Mitglieder erlauben. Die zuletzt besprochene Empfehlung war live/dynamisch als Standard, dauerhafte Übernahme optional; dieser Zusatz wurde nicht ausdrücklich endgültig entschieden.

6. Datenhoheit, selektiver Index und temporäre Verarbeitung

Datenklasse Grundverhalten
Originaldokumente, E-Mail-Original, Dateien Verbleiben in führender Quelle
Quellreferenzen und technische IDs Bei Verknüpfung dauerhaft in Tsumugu
Tsumugu-eigene Akten, Notizen, Beziehungen, Aufgaben, Fristen, Finanzzuordnungen Dauerhafte Tsumugu-Daten
Relevante Quellmetadaten Selektiv und freigegeben indexierbar für Suche/Fristen/Navigation
Volltexte, OCR, PDFs, Vorschauen Kein generelles permanentes Spiegeln; auf Abruf, bei Bedarf temporär
KI-Arbeitstexte/-Zwischenergebnisse Zweckgebunden und kurzlebig; definierter Standort, Aufbewahrung und Löschung
KI-abgeleitete Metadaten Vorschlag mit Herkunft/Prüfstatus; selektiv bestätigte Fakten in Tsumugu nutzbar
Wiederverwendbare KI-Artefakte / Analysen Optional dauerhaft im lokalen oder zentralen Artifact Storage, gemäß Daten- und Verarbeitungsrichtlinie
.eml-Archivkopie Nur am konfigurierten lokalen Ablageort, nicht im SaaS-Dateispeicher
Zugangsdaten einer lokalen Quelle Vertrauenswürdige lokale Connector Runtime; nicht als Nutzdaten an SaaS senden

Verbindliche SaaS-Option: Kunden können jede dauerhafte Cloud-Speicherung von Dokumentinhalten und KI-Artefakten deaktivieren. Dann verbleiben zentral nur Tsumugu-eigene Akteninformationen, freigegebene Metadaten und Referenzen. Dies bedeutet nicht, dass bei gesondert genehmigter externer Analyse niemals Daten übertragen werden. Temporäre Übertragungen, Caches und Logs sind separat zu kontrollieren.

Datenrichtlinien gelten pro Connector-Instanz und Datenklasse und unterscheiden mindestens: dauerhaft speichern, temporär zwischenspeichern, für Live-Funktion übertragen, an externen Processor weitergeben. Konkrete Feldlisten/Schutzprofile werden bei Implementierung des jeweiligen Connectors festgelegt, nicht als globales Vollschema aller Quellen.

Metadatenhoheit (bestätigt): Quellmetadaten werden bei vorhandenen Schreibrechten im führenden Quellsystem bearbeitet; nach Erfolg wird der Tsumugu-Index aktualisiert. Tsumugu-eigene Felder bleiben separat. Kein automatisches Zurückschreiben von Tsumugu-Feldern in die Quelle. Bei konkurrierenden Änderungen möglichst Konflikterkennung statt stiller Überschreibung.

Aktualisierung (bestätigte Richtung): Bedarfsgesteuert beim Öffnen, ereignisbasiert wenn möglich und/oder periodisch. Standardmäßig referenzierte Ressourcen und dynamische Sammlungen; optionale umfassendere Indexierung. Live-Suche des gesamten berechtigten Quellbestands bleibt unabhängig davon möglich.

7. IMAP: dauerhafte Referenzen und optionale .eml-Sicherung

Verbindlich beschlossen: Jede IMAP-Connector-Instanz erhält eine Archivierungsoption:

Modus Verhalten
automatic (Standard) Explizite Zuordnung einer E-Mail zu einer Akte löst lokale .eml-Sicherung aus
manual Sicherung nur auf Nutzeraktion
disabled Keine .eml-Archivierung
  • Bloße Mitgliedschaft in einer dynamischen Sammlung löst keine automatische Sicherung aus.
  • .eml wird über lokale Runtime am konfigurierbaren Ablageort, z.B. NAS, gesichert; nicht im zentralen SaaS.
  • Akteneintrag kann IMAP-Original und lokale Archivkopie als alternative Locator derselben Ressource kennen.
  • Erfolg erst nach geprüfter Ablage melden; Integritätsmerkmal (z.B. Prüfsumme), Zeitpunkt und Fehlerstatus festhalten.
  • Archivkopie ist nicht automatisch revisionssicheres Archiv oder vollständige Backupstrategie.
  • Der Zugriff auf lokale Archivkopien ist ebenfalls zu autorisieren; keine Erhöhung von Berechtigungen durch bloße Existenz einer Kopie.

8. Berechtigungs- und Sichtbarkeitsmodell

Der effektive Zugriff auf eine externe Ressource setzt voraus:

  1. die Erlaubnis durch Tsumugu (Datenraum, Akte, Freigabe bzw. Connector-Nutzung), und
  2. die Berechtigung der verwendeten Quellidentität sowie die jeweilige Connector-Fähigkeit.

Pro Connector-Instanz können individuelle Benutzerzugänge oder ein verwalteter gemeinsamer Zugang genutzt werden. Bei gemeinsamem API-Key/Service-Konto darf dessen technischer Zugriff nicht unkontrolliert auf alle Tsumugu-Nutzer übertragen werden. Der Kontext des aufrufenden Nutzers und die zulässige Delegation sind bei jeder Operation relevant.

Die Suche und Navigation umfassen grundsätzlich den vollständigen durch diese Rechte erreichbaren Quellbestand, nicht bloß bereits gespeicherte Referenzen. Eine Aktenfreigabe allein darf keine unberechtigten externen Inhalte offenlegen. Offline-Status und fehlende Quellrechte müssen unterscheidbar angezeigt werden.

9. Präsentationsvertrag und UI-Grenze

Connectoren sollen neben Daten und Fähigkeiten deklarative UI-Metadaten liefern können (Ressourcentyp, Felder und Feldtypen, Labels, erlaubte Operationen, Navigationsstruktur, verfügbare Vorschau- oder Editorarten).

Bevorzugte Stufen:

  1. Generische Tsumugu-Komponenten: Baum/Navigation, Liste/Tabelle, Suche/Filter, Detail/Metadaten, Vorschau, Formular/Metadateneditor.
  2. Registrierte, Tsumugu-eigene Spezialansichten: z.B. E-Mail-Thread, Buchungsdetails oder PDF-Viewer, soweit fachlich nötig.
  3. Von Connectoren gelieferter ausführbarer Frontend-Code: nicht Bestandteil der anfänglichen Zielarchitektur; später nur bei nachgewiesenem Bedarf und mit eigenem Sicherheitskonzept.

Ziel ist kein universeller Low-Code-UI-Generator und keine vollständige Nachbildung der Oberflächen von Paperless, E-Mail-Clients oder Bankportalen. Der volle berechtigte Datenbestand ist navigier-/durchsuchbar; Bearbeitung wird nur für konkret angebotene Fähigkeiten umgesetzt.

10. Querschnittsfähigkeiten und Vertragsgrenzen

Gemeinsamer Minimalvertrag für Source-artige Connectoren (konzeptionell):

  • Identität, Instanz und angebotene Fähigkeiten ermitteln.
  • Navigation/Listen und Suche innerhalb der Quellrechte.
  • Ressource auflösen, Metadaten lesen, Inhalt/Vorschau bei Fähigkeit abrufen.
  • Unterstützte Schreib-/Exportoperationen autorisiert ausführen.
  • Änderungen erkennen bzw. selektiven Index aktualisieren, soweit unterstützt.
  • Verständliche Zustände melden: nicht erreichbar, nicht berechtigt, nicht auffindbar, veraltet, Konflikt, Fehler.

Kein falscher Universalvertrag: Banking benötigt transaktionale Semantik, KI einen Processing-Vertrag und lokaler Storage einen Ablage-/Abrufvertrag. Gemeinsame Technik wird nur bei konkret gemeinsamem Bedarf herausgezogen.

Sicherheitsgrenzen: Quellzugangsdaten geschützt verwahren; starke Authentisierung der lokalen Runtime gegenüber SaaS; Autorisierung pro Operation; keine willkürlichen Dateipfade und keine überprivilegierten Service-Accounts; sichere Vorschau/Rendering; kontrolliertes Egress und Löschung temporärer Daten. Konkrete Technologieentscheidungen werden in den zuständigen technischen Blueprints geprüft.

11. Storage- und Result-Management-Architektur (konsolidiert v0.2)

11.1 Verantwortlichkeiten

Baustein Verantwortlichkeit Nicht seine Aufgabe
Tsumugu Core / Result Management Verknüpft Ergebnis mit Akte/Ressource, kennt Herkunft, Quellstand, Status, Zugriffsrechte, Wiederverwendbarkeit und Speicherreferenz Große Artefakte ungefragt in die Core-Datenbank aufnehmen
Artifact Storage Speichert/liest/löscht Inhalte, gewährleistet Integritätsprüfung, Version-/Ablagebezug und geregelte Retention Fachliche Rechnungsinterpretation oder KI-Entscheidungen
Connector Runtime Autorisierter Zugriff auf lokale Quellen/Speicher; führt lokal erlaubte Ablage und Abholung aus Umgehung von Quellrechten oder Datenrichtlinien
Processing Connector Erzeugt Ergebnisse aus explizit autorisierten Eingaben Legt Datenresidenz oder Aufbewahrung eigenmächtig fest

Das Modell unterstützt eine fachliche Ressource mit mehreren Zugriffspfaden (z.B. IMAP und gesicherte .eml-Kopie) und mehrere aus ihr abgeleitete Artefakte (z.B. OCR-Text, Extraktions-JSON, Zusammenfassung). Diese sind nicht mit dem Original identisch und müssen nicht im selben Speicher liegen.

11.2 Speicherentscheidung

Kein pauschaler Vorrang lokaler Ablage. Eine lokale Runtime kann langsam oder zeitweise unerreichbar sein; bei externer KI-Verarbeitung werden erlaubte Inhalte ohnehin zeitweise übertragen. Die Datenschutzwirkung hängt daher stärker vom gesamten Datenfluss, Schlüsselzugriff und Verarbeitungsort als nur vom physischen Speicherort ab.

Grundsätzliche Speicheroptionen:

  • SaaS-/Managed-Storage: Für ausdrücklich freigegebene abgeleitete Ergebnisse; gute serverseitige Verfügbarkeit. Verschlüsselung und kontrollierte Löschung sind Pflicht. Serverseitige Verschlüsselung allein bedeutet nicht, dass der Betreiber keine Klartextzugriffsmöglichkeit besitzt.
  • Lokaler Storage: Für sensible Inhalte oder Nutzerpräferenzen; lokale Verfügbarkeit hängt von Runtime/NAS und Verbindung ab. Lokale Verarbeitung kann tatsächliche Übertragung vermeiden.
  • Hybrid: Auswahl nach Datenklasse und Connector-Instanz, getrennt nach Speicherung, temporärem Zugriff und externer Verarbeitung.

SaaS-Cloud-Content-Opt-out ist verbindlich: Originalinhalte und KI-Artefakte müssen ohne dauerhafte Cloud-Speicherung verwendbar sein. Die dafür benötigten Tsumugu-eigenen Akteninformationen und freigegebenen Metadaten bleiben separat behandelbar.

11.3 Mindestfähigkeiten des Storage-Vertrags

  1. put/get/delete für typisierte Artefakte (Dateien, Text, JSON etc.), nur nach Autorisierung und Policy-Prüfung.
  2. Referenzen und alternative Speicherorte statt ungefragter Binärkopien im Core; stabile Zuordnung zu Quellressource und ggf. Verarbeitungsstand.
  3. Integrität und nachvollziehbarer Status: Prüfsumme, erfolgreiche bestätigte Ablage, Unterscheidung zwischen vorhanden, nicht erreichbar, nicht autorisiert und nicht mehr vorhanden.
  4. Version und Herkunft: Ergebnis kann einem bestimmten Quell-/Analysezustand zugeordnet und bei Quelländerung als möglicherweise veraltet erkannt werden.
  5. Aufbewahrung und Löschung: Dauerhaft vs. befristet, Löschung inklusive geregelter Cache-/Backup-Fristen; keine falsche Garantie sofortiger physischer Löschung aller Sicherungskopien.
  6. Sichere lokale Speicherpfade und Schlüsselverwaltung: Kein vom Client frei vorgebbarer Dateisystempfad, keine Rechteausweitung durch Archivkopien.
  7. Kontrollierbare Abrufwege: Bei lokaler Ablage kann SaaS die Referenz anzeigen, aber Inhalte nur bei erreichbarer und autorisierter lokaler Runtime ausliefern.

Keine Pflicht zur universellen Dateiversionierung, geografischen Replikation, komplexen Storage-Abstraktion oder zentralen Search-Index-Engine für den MVP.

11.4 Wiederverwendung von KI-Ergebnissen

Ein Analyseergebnis darf nur dann als aktuell wiederverwendet werden, wenn Verarbeitungsaufgabe, Quellstand und Prüfstatus geeignet sind. Der Core verwaltet knappe, relevante Ergebnis-Metadaten; das größere Artefakt kann lokal oder zentral liegen. Fachliche Bestätigungen (z.B. ein akzeptierter Rechnungsbetrag) werden als Tsumugu-Daten geführt und nicht mit unbestätigten KI-Vorschlägen vermischt.

11.5 Betriebliche Mindestfragen – zur Umsetzung, nicht jetzt als Plattformprojekt

Für den Hybridbetrieb bleiben drei technische Klärungen: (a) sicherer SaaS-zu-Lokal-Kanal, vorzugsweise ohne eingehende Kundenports, (b) Autorisierung jeder Aktion einschließlich gemeinsamer Quellkonten, (c) Einrichtung, Updates und Verbindungs-/Versionskompatibilität der lokalen Runtime. Verfügbarkeit und erwartbare Abrufgeschwindigkeit sind bei der ersten produktiven Hybridstrecke praktisch zu messen.


12. Technische Referenzarchitektur und Umsetzungsmodus

Der separate Jinkendo-Architektur-Workstream betreut technische Standards/Blueprints (u.a. Auth/Scopes, Release/Recovery, KI-Gateway/Privacy, Workflows, Entitlements/Quotas, Medien/Rendering). Tsumugu liefert die fachlichen Modulanforderungen. Bei größeren Modulen wird zunächst geprüft, ob vorhandene Jinkendo-Implementierungen und Blueprints anwendbar sind. Neue Spezial-Blueprints nur bei Bedarf; keine pauschale Blueprint-Produktion. Konzepte sind nicht automatisch getestet oder produktionsreif.

Schlanker Realisierungspfad (Vorschlag, keine freigegebene Roadmap):

  1. Erstes durchgängiges Source-Szenario mit Paperless: Navigation/Suche → Referenzieren → Metadaten → Akte/Preview → Quell-Edit, falls nötig.
  2. Gemeinsame Resource/Locator/Berechtigungs-/Datenpolicy-Prinzipien anhand IMAP inkl. optionaler .eml-Sicherung validieren.
  3. Dynamische CollectionBindings, lokale Hybrid-Runtime und selektiver Index nach echten Use Cases absichern.
  4. Banking read-only und KI/Processing jeweils als begrenzte eigene Integrationen ergänzen.

Die Reihenfolge steht unter fachlichem MVP-Vorbehalt und ist keine Verpflichtung, alles vor dem ersten Release zu bauen.

13. Nur noch wesentliche offene Architekturfragen

Thema Klärung bei Warum relevant
Hybrid-SaaS ↔ lokale Runtime: Verbindung, Vertrauensgrenze, Live-Zugriff Vor Hybrid-Implementierung Sicherheit, Erreichbarkeit, Datenschutz
Datenprofile pro konkreter Connector-Instanz, inkl. Vorschau, Suche, Cache/Logs Je Connector-Implementierung Wirkliche Datenkontrolle statt nur Marketingversprechen
Identität/Recovery beim Verschieben von IMAP-/Datei-Ressourcen Bei IMAP-/Datei-Anbindung Haltbare explizite Referenzen
Rechte auf Akten-/Unterakten-/Ressourcenebene und Delegation gemeinsam genutzter Quellzugänge Vor Mehrnutzer-Freigabe Keine Datenlecks
Dynamische Sammlung: optionale dauerhafte Übernahme bei Austritt Wenn benötigt Bewusst nicht festgelegt
Konkrete KI-Use-Case-Priorität, Eingabe-/Ergebnisumfang und Freigaben Vor KI-Funktion Verarbeitung und fachliche Korrektheit
Artifact-Storage-Adapter, Verschlüsselung/Schlüsselmodell, Retention und tatsächliche Löschwege Vor Storage-Implementierung Datenhoheit, Verfügbarkeit und Compliance
Banking-Anbieter/Einwilligung und Datenfeldumfang Vor Banking-Funktion Technische und rechtliche Realisierbarkeit

Bewusst nicht jetzt vertiefen: generisches Plugin-Sandboxing für UI-Code, universelle Editor-DSL, vollautomatisches Daten-Mirroring, jede mögliche Synchronisationskonfliktklasse, universelle KI-Workflow-Engine, zentraler Lizenz-/Billingdienst.

14. Status- und Entscheidungsspur

Festgelegt in der aktuellen Unterhaltung (einschließlich Entscheidungen nach v0.1): Dualer Betriebsansatz Self-Hosted/SaaS; Hybrid mit lokaler Runtime als bevorzugte Richtung; Daten überwiegend in Quellen; vollständige berechtigte Navigation/Suche; Rechte aus Quellsystem und Tsumugu; individuelle und gemeinsam verwaltete Quellzugänge; unterschiedliche Connector-Fähigkeiten; generische UI vor Connector-Frontend-Code; eigene Notizen/selektive Metadaten in Tsumugu; zeitweise Textverarbeitung; Referenzen und dynamische Sammlungen; explizite Referenzen trotz Ordnerwechsel; IMAP .eml-Archivmodi mit automatic als Standard, Archiv ausschließlich lokal; Quellmetadaten im Quellsystem editieren, eigene Tsumugu-Felder getrennt; standardmäßig referenzierte Ressourcen und dynamische Sammlungen aktualisieren, Vollindex optional; Banking zunächst read-only, keine gesamte Buchungshistorie standardmäßig, nur zugeordnete Buchungsreferenzen/-metadaten persistent; KI-Processing mit Text, Bild, PDF und strukturierten Daten sowie lokalen/externen Anbietern; bestehende OCR bevorzugt, multimodale PDF-/Bildinterpretation möglich; sechs grundlegende KI-Aufgaben, kombinierbare Verarbeitungsschritte, Wiederverwendung mit Herkunft/Prüfstatus; Ergebnisse lokal oder zentral nach Policy speicherbar; separate Datenfreigabe für externe Verarbeitung; ausdrücklicher SaaS-Schalter zum vollständigen Verbot dauerhafter Cloud-Speicherung von Dokumentinhalten und KI-Artefakten; Storage mit Artifact-Ablage, Integrität, Retention und Result Management.

Architekturvorschläge, noch keine eigenständigen Beschlüsse: Namen der logischen Objekte und APIs; konkrete UI-Deklarationsstruktur; drei konkrete Betriebsvarianten als technische Deployments; technischer Umsetzungsplan; Cache-TTLs, Protokolle und Feldlisten; optionale Sticky-Sammlung; konkrete API-Signaturen und Speichertechnologien, Verschlüsselungs-/Schlüsselimplementierung und Retrieval-/Verfügbarkeits-SLOs.

Dokumentpflege: Jede neue Entscheidung soll gezielt im betroffenen Abschnitt und in dieser Entscheidungsspur ergänzt werden. Keine stillschweigende Umdeutung der Tsumugu-Produkt-Baseline oder Erhebung einer Tsumugu-Lösung zum allgemeinen Jinkendo-Standard.