5. Bausteinsicht

Die Bausteinsicht beschreibt die statische Zerlegung des Systems in Bausteine (Module, Komponenten, Subsysteme, Pakete …) und deren Beziehungen. Sie zeigt die Gesamtstruktur des Quellcodes. Diese Sicht ist in einer Top-down-Hierarchie organisiert.

5.1 CIMgate.HUB Knoten (Whitebox)

Bausteinsicht – CIMgate.HUB Knoten (Whitebox)

In dem Diagramm sind einige Abhängigkeiten zur Übersicht nicht eingezeichnet. Dies sind unter anderem Verbindungen zu Hub.Core, das von allen Projekten referenziert wird, sowie der Schreibzugriff von Hub.Sync auf die CX5-Datenbank.

Motivation der Zerlegung

Durch die bereits bestehende Arbeit vor der Interschutz, sowie dem Einsatz der PowerSync Komponente in Mobile, hat sich das Konzept den WAL der Datenbank auszulesen durchgesetzt. Dieses Konzept hat an CommandX einen automatischen Event-Source-Stream angehängt, ohne den Programmcode von CommandX an vielen Stellen kontinuierlich erweitert werden musste.

Somit bleiben für den CIMgate.HUB die folgenden Aufgaben für sein Betrieb zu erfüllen:

Aufbereiten und Verstehen der anfallenden Daten und Events (Sync)
Entscheiden, welche Daten welchen Partner erreichen (Collaboration)
Verbinden und Authentifizieren von Partner auf technischer Ebene (Connectivity)
Protokollieren und Schaffen von Transparenz für Administratoren (Operations)
Steuerung durch Benutzer in CX5 (Api)

Ergänzend gibt es drei Bausteine ohne eigene Fachaufgabe:

Hub.Schema ist eigenständig, da die Tabellenklassifizierung als Teil von CommandX.WEB gepflegt wird und das Schema-Tooling gesondert umgesetzt wird (OC-02). Der Baustein kapselt diese Abhängigkeit.
Hub.Core hält die gemeinsamen Verträge, damit die Fachbausteine sich nicht gegenseitig referenzieren müssen.
Hub.Host bündelt Start, Konfiguration und Lebenszyklus, damit die Fachbausteine unabhängig vom Hosting bleiben (Betreibbarkeit, docker-compose je Knoten).

Enthaltene Bausteine

Diese Aufgaben lassen sich wie folgt auf die Bausteine aufteilen:

Baustein	Aufgabe
`Hub.Sync`	Entgegennahme aller Events, Klassifizierung nach Schema, Übernehmen von eingehenden Änderung, Konfliktauflösung, Initialabgleich, zyklenfreie Weiterleitung von Änderungen
`Hub.Collaboration`	Verwaltung über Partner, Sync-Profile sowie deren Kopplung, Shares und Einladungen. Liefert Regeln für `Hub.Sync`, wird von `Hub.Connectivity` genutzt um die Topologie aufzubauen
`Hub.Connectivity`	Verbindet und authentisiert Partner, ordnet Knotenidentität Partnern zu, verwaltet Credentials, führt das Hub-Protocol, erzeugt NATS-Konfiguration, mDNS Discovery
`Hub.Operations`	Audit, Fehlerliste, Metriken und Admin Dashboards, verwaltet Debezium und die Anbindung an die CX5 Datenbank
`Hub.Api`	Schnittstellen zur Steuerung der Bausteien aus CX5
`Hub.Schema`	Schema Registry: Tabellenklassifizierung, Avro-Schemata, Validierung und Versionsabgleich auf Modulebene
`Hub.Core`	Hält gemeinsame Verträge die über alle Bausteine genutzt werden und enthält selbst keine Fachlogik
`Hub.Host`	AppHost, Konfiguration, Lebenszyklus, Dependency Injection, Hintergrunddienste

Fremd- und Infrastrukturbausteine (nicht selbst entwickelt, Teil des Knotens):

Baustein	Technologie (TC-01)	Aufgabe
`Hub.DB`	PostgreSQL 18 (Annahme)	Source of Truth des HUB: Partner, Kopplungen, Shares, Credentials, Audit, Sync-Zustand
Debezium	Debezium 2.7 (pgoutput)	Liest die logische Replikation der CX5-DB und publiziert Zeilenänderungen auf `cdc.raw.*`
NATS JetStream	NATS 2.10	Persistente Streams, Leafnode-Verbindungen zu Partnern, Accounts, Subject-Berechtigungen

Wichtige Schnittstellen

Von → Nach	Bezeichnung	Protokoll	Inhalt
CommandX →`Hub.Api`	Control-Plane-API	HTTPS/JSON`/api/v1`, SSE	Einladungen, Kopplungen, Shares, Zugriffsanfragen; Status als Push
CX5-DB → Debezium	CDC	PostgreSQL pgoutput MSSQL CDC	Zeilenänderungen aller klassifizierten Tabellen
Debezium → NATS	`cdc.raw.*`	NATS JetStream	Rohereignisse je Tabelle
NATS ↔`Hub.Sync`	verabeitung cdc, Sync-Streams	NATS JetStream, explizites Ack	Rohereignisse ein; Collab-, Snapshot- und Status-Subjects ein/aus
`Hub.Sync`→ CX5-DB	Apply	Transaktion je Nachricht/Batch	Eingehende Änderungen inkl. Sync-Metadaten
`Hub.Sync`→`Hub.Schema`	Klassifizierung	In-Process	Modulzuordnung, Schema-Validierung, Schema-Version
`Hub.Collaboration`→`Hub.Connectivity`	Topologie	In-Process	Welche Partner mit welchen Profilen verbunden sein müssen
`Hub.Connectivity`→ NATS	Konfiguration	Generierte Konfigurationsdateien, Reload, Hub-Protokoll	Accounts, Subject-Berechtigungen, Leafnodes, Streams, Handshakes, Einladungen, Partner-Verbindungen
NATS ↔ Partner-HUB	Data Plane	NATS-Leafnode, TLS 1.3	Collab-, Snapshot-, Status- und Objekt-Subjects, Handshake, Versionsprüfung, Einlösung, Kopplungsbestätigung
`Hub.Collaboration`→`Hub.Operations`	Audit-Ereignisse	In-Process	Kopplungs- und Teilungsaktionen mit Korrelations-ID
`Hub.Sync`→`Hub.Operations`	Konflikte, Metriken	In-Process	Konfliktprotokoll, fehlerhafte Datensätze, Durchsatz und Latenz
`Hub.Operations`→ Monitoring	Telemetrie	OTLP → Grafana	Metriken, Traces, Logs

5.2 Ebene 2

5.2.1 Hub.Sync (Whitebox)

---
config:
  theme: mc
  layout: dagre
---
flowchart LR
    NATSin[("NATS<br/>cdc.raw.*")]
    NATSpeer[("NATS<br/>Partner-Subjects")]
    NATSout[("NATS<br/>Collab-Subjects<br/>je Prioritätsklasse")]
    CX5[("CX5-DB")]
    Schema["Hub.Schema"]
    Collab["Hub.Collaboration"]
    Ops["Hub.Operations"]

    subgraph Sync["Hub.Sync"]
        direction LR
        subgraph Out["Ausgehend"]
            Ingest["Sync.Ingest"]
            Classify["Sync.Classification"]
            Origin["Sync.Origin<br/>Zyklenschutz"]
            Routing["Sync.Routing"]
            Outbound["Sync.Outbound"]
        end
        subgraph In["Eingehend"]
            Inbound["Sync.Inbound"]
            Conflict["Sync.Conflict"]
            Apply["Sync.Apply"]
        end
        subgraph Sn["LSN"]
            Snapshot["Sync.Snapshot"]
        end
        Retry["Sync.Retry"]
    end

    NATSin --> Ingest --> Classify --> Origin --> Routing --> Outbound --> NATSout
    NATSpeer --> Inbound --> Conflict --> Apply --> CX5
    Classify -. Schema .-> Schema
    Inbound -. Schema .-> Schema
    Routing -. Regeln .-> Collab
    Inbound -. Rechte .-> Collab
    Snapshot --> Outbound
    Snapshot --> Apply
    Apply -. fehlgeschlagen .-> Retry
    Retry --> Ops
    Conflict -. Konflikte .-> Ops

Motivation

Ausgehender und eingehender Pfad sind getrennt, da sie unterschiedlich skalieren und unterschiedliche Fehlerfälle haben.
Rechte werden im Broker (Subject-Berechtigungen) und in Sync.Inbound geprüft. Eine fehlerhafte Broker-Konfiguration führt so nicht zu unberechtigten Schreibzugriffen.
Der Zyklenschutz ist ein eigener Baustein, da jede angewendete Änderung über den WAL erneut als CDC-Ereignis erscheint. Ohne ihn würden Änderungen zwischen gekoppelten Knoten endlos gespiegelt.
Snapshot und Initialabgleich haben einen anderen Lebenszyklus als der laufende Strom und sind deshalb getrennt.

Enthaltene Bausteine

Baustein	Aufgabe	Anforderung
`Sync.Ingest`	Konsumiert `cdc.raw.*` aus JetStream wartet auf die Verarbeitung durch die anderen Komponenten und gibt explizites Ack	A-005
`Sync.Classification`	Ordnet jede Zeilenänderung über `Hub.Schema` einem Modul und ggf. Einsatz zu; verwirft lokale Bereiche und nicht klassifizierte Tabellen	B-010, B-016
`Sync.Origin`	Erkennt anhand der Sync-Metadaten Änderungen, die aus einem eigenen Apply stammen, und leitet sie nicht erneut weiter (PropagationKey)	–
`Sync.Routing`	Ermittelt anhand der Regeln aus `Hub.Collaboration` die Ziel-Partner und die Prioritätsklasse, überprüft das Event auf Konfiguration, Regeln und fehlerhafte Payloads	A-006
`Sync.Outbound`	Publiziert auf das Collab-Subject	A-006
`Sync.Inbound`	Konsumiert Änderungen der Partner, validiert Schema-Version und prüft Schreibrechte je Modul	A-010
`Sync.Conflict`	Feldweises LWW auf Basis von Änderungszeitstempeln je Feld; protokolliert Konflikte an Betroffene	A-003
`Sync.Apply`	Schreibt per EF Core in einer Transaktion je Nachricht/Batch inkl. Sync-Metadaten in die CX5-DB	–
`Sync.Snapshot`	Initialabgleich per Snapshot + LSN-Catch-up, Tombstones, Zusammenführen nach Trennung, Nachreichen des Endstands, Bereinigung inaktiver Einsätze	B-003, B-005, B-013
`Sync.Retry`	Retry mit Backoff, DeadLetterQueue, Meldung fehlerhafter Datensätze an`Hub.Operations`	A-009

Wichtige Schnittstellen

Schnittstelle	Beschreibung
`Sync.Routing`→`Hub.Collaboration`	Abfrage der effektiven Regeln: für eine Änderung (Modul, Einsatz, Befehlsstelle) die Partner und Rechte
`Sync.Inbound`→`Hub.Collaboration`	Prüfung, ob der sendende Partner für das Modul schreibberechtigt ist
`Sync.Apply`→ CX5-DB	Transaktionaler Schreibzugriff; die Sync-Metadaten sind Grundlage für `Sync.Origin` und `Sync.Conflict`

5.2.2 Hub.Collaboration (Whitebox)

flowchart TB
    Api["Hub.Api"]
    Conn["Hub.Connectivity"]
    Sync["Hub.Sync"]
    Ops["Hub.Operations"]
    DB[("Hub.DB")]

    subgraph Collab["Hub.Collaboration"]
        direction TB
        Partner["Collaboration.Partner"]
        Coupling["Collaboration.Coupling"]
        Profiles["Collaboration.Profiles"]
        Invitations["Collaboration.Invitations"]
        Shares["Collaboration.Shares"]
        Rules["Collaboration.Rules"]
    end

    Api --> Coupling
    Api --> Invitations
    Api --> Shares
    Conn -. Einlösung prüfen .-> Invitations
    Coupling --> Partner
    Coupling --> Profiles
    Invitations --> Shares
    Shares --> Profiles
    Coupling --> Rules
    Shares --> Rules
    Rules -- Regeln --> Sync
    Rules -- Topologie --> Conn
    Collab -.->|Audit-Ereignisse| Ops
    Collab --> DB

5.2.3 Hub.Connectivity (Whitebox)

flowchart TB
    Collab["Hub.Collaboration"]
    Api["Hub.Api"]
    Ops["Hub.Operations"]
    Schema["Hub.Schema"]
    NATS[("NATS")]
    DB[("Hub.DB")]

    subgraph Conn["Hub.Connectivity"]
        direction TB
        Trust["Connectivity.Trust"]
        Credentials["Connectivity.Credentials"]
        Protocol["Connectivity.Protocol"]
        Reconcile["Connectivity.Reconcile"]
        Health["Connectivity.Health"]
        Discovery["Connectivity.Discovery"]
    end

    Peer <-->|HTTPS + JWT| Protocol
    Protocol --> Trust
    Protocol -. Versionsprüfung .-> Schema
    Protocol -. Einladungen.-> Collab
    Trust --> Credentials
    Collab -- Topologie --> Reconcile
    Credentials --> Reconcile
    Reconcile -- Konfiguration --> NATS
    NATS -. Verbindungszustand .-> Protocol
    Protocol --> Health
    Health -- Status --> Api
    Health -. Verbindungsabbrüche .-> Ops
    Discovery -. mDNS .-> Protocol
    Trust --> DB
    Credentials --> DB

5.3 Ebene 3

Sync.Conflict (feldweises LWW, A-003)