# Systemkontext und Prinzipien

> Zweck, Hauptfunktionen, Architekturprinzipien, die zwei Verarbeitungsphasen sowie Betriebs- und Skalierungsmodell der dsyr.DataBridge.

---

Site [llms.txt](/llms.txt)

---

## Zweck

Die dsyr.DataBridge ist eine serverlose **Datenintegrations-Bridge** auf Azure Functions
(.NET 10, Isolated Worker). Sie synchronisiert Datensätze nahezu in Echtzeit zwischen
heterogenen Geschäftssystemen, ohne diese direkt zu koppeln. Quelle und Ziel sind über
**Azure Service Bus** entkoppelt, Änderungen werden über Watermarks change-getrieben
übertragen.

Die Bridge hält **keine Fachdaten** dauerhaft. Sie speichert nur Konfiguration und
Synchronisationsstände in Azure Table Storage; Nachrichten liegen transient im Service Bus.

## Hauptfunktionen

| Funktion | Beschreibung |
|---|---|
| Change Detection | Periodisches Pollen der Quellsysteme (Timer `GetChanges`, optional Durable-Orchestrierung) |
| Asynchrone Entkopplung | Erkannte Änderungen landen als Nachrichten in priorisierten Queues (Low / Standard / High) |
| Feld-Mapping und Transformation | Konfigurierbare Zuordnung inkl. Typ-Coercion, Default-Werten, Option-Mapping, Lookups, Source-/Target-Operationen |
| Multi-System-Konnektivität | D365 BC, CE/Dataverse, NAV, generische REST-APIs über OpenAPI-Spezifikation, SQL-Datenbanken (MSSQL, PostgreSQL, MySQL, Oracle) |
| Idempotente Zielverarbeitung | Upsert/Delete über Primär-, Custom- oder Filter-Keys, mehrere Schlüssel mit Rangfolge |
| Aktions-Jobs | `InvokeAction` ruft benannte Nicht-CRUD-Endpunkte auf (OpenAPI `operationId`, CE `OrganizationRequest`) |
| Watermarking | Persistierter Stand pro Job, nur neue Änderungen werden übertragen |
| Response-Jobs | Rückschreiben von im Ziel erzeugten Schlüsseln in die Quelle |
| Diagnose und KI-Anbindung | HTTP-Endpunkte (`CheckList`, `Validate`, `JobApi`, `MappingApi`) und ein read-only MCP-Server |
| Selektive Telemetrie | Gepuffertes Logging pro Invocation, Dependency-Sampling, pre-aggregierte Custom Metrics |
| Fehlerresilienz | Backoff-Retry, Transitive-Queues, Dead-Letter-Queues, Alerts |

## Zielgruppen

| Zielgruppe | Nutzen |
|---|---|
| Integrations-/ERP-Berater | Konfigurieren Connections, Jobs und Mappings in Table Storage, ohne Code zu deployen |
| Cloud-/DevOps-Engineers | Deployen via Bicep oder Marketplace, betreiben und überwachen die Function App |
| Entwickler | Erweitern Connectoren, Resolver und Source-Operationen in `DataBridge.Core` |
| KI-Assistenten | Lesen Konfiguration und Queue-Zustand über den MCP-Server |

## Architekturprinzipien

| Prinzip | Umsetzung |
|---|---|
| Separation of Concerns | Host (Trigger) ↔ Core (Logik) ↔ Connectoren (System-Anbindung) ↔ Resolver/Mapper (Transformation) |
| Configuration over Code | Connections, Jobs, Mappings, Watermarks liegen in Table Storage |
| Lazy Initialization | Services sind DI-Singletons; die Konfiguration wird einmalig und thread-sicher beim ersten Aufruf geladen |
| Asynchrone Entkopplung | Service Bus zwischen Lese- und Schreibseite; jede Nachricht wird isoliert verarbeitet |
| Idempotenz | Upsert/Delete über definierte Target-Keys |
| Resilienz | Backoff, Lock-Renewal, Transitive-Queues, Dead-Letter-Queues, `DeadLetterMover` |
| Erweiterbarkeit | Source-Operation-Handler werden per Reflection registriert; Connectoren über `ConnectionTypes` gemappt; Resolver-Registries je Connector als statische `FrozenDictionary` |
| Observability first | Gepuffertes Logging, Requests und Exceptions nie gesampelt, Custom Metrics ohne Sampling |

## Die zwei Phasen

```mermaid
flowchart LR
    SRC["Quellsystem"] -->|"1. Erkennung (Pull)"| FUNC1["GetChanges<br/>oder Orchestrator + Activity"]
    FUNC1 -->|"QueueMessage"| SB[("Service Bus<br/>Low / Standard / High")]
    SB -->|"2. Verarbeitung (Push)"| FUNC2["Process*QueueItems"]
    FUNC2 -->|"Upsert / Delete / Action"| TGT["Zielsystem"]
    FUNC1 -.->|"Watermark"| WM[("watermark")]
    FUNC2 -.->|"Response-Job / Transitive / Ignored"| SB
```

- **Erkennung:** `GetChanges` (Timer) liest Änderungen aus den Quellsystemen und
  enqueued sie. Die Durable-Orchestrierung ist eine Alternative, die nur per HTTP
  gestartet wird und im Regelbetrieb nicht läuft.
- **Verarbeitung:** Drei Service-Bus-Trigger (je Priorität) dequeuen und schreiben ins
  Zielsystem.

Diese Entkopplung erlaubt unabhängige Skalierung beider Seiten und überbrückt temporäre
Ausfälle des Zielsystems. Details in [Datenflüsse](../datenfluesse/).

## Serverless-Modell

- Azure Functions v4, .NET 10, Isolated Worker (`FUNCTIONS_WORKER_RUNTIME=dotnet-isolated`).
- App Service Plan **Y1 (Consumption, Windows)** als Standard, optional EP1–EP3 über den
  Bicep-Parameter `appServiceSku`.
- `functionAppScaleLimit` begrenzt die Instanzen (Default 12).
- Durable Functions mit Azure-Storage-Provider (`DurableFunctionsHub`).
- Auslieferung als Run-from-Package-Zip; alternativ als Container-Image (siehe
  [Container-Betrieb](/docs/einrichtung/container-betrieb/)).

## Betriebsmodell

- **Trigger-gesteuert:** Timer, Service Bus, HTTP, Durable.
- **Single-Message-Processing:** `autoCompleteMessages = false`, manuelles Complete/Abandon;
  `maxConcurrentCalls = 12` je Instanz.
- **Function-Timeout:** 10 Minuten (`host.json`).
- **Einzelne Functions abschaltbar** über `AzureWebJobs.<Name>.Disabled`; Bicep setzt das
  über den Parameter `disabledFunctions`.
- **Konfigurations-Cache pro Prozess:** Änderungen an den Tabellen greifen erst nach
  einem Neustart der Function App.

## Skalierungsmodell

| Stellschraube | Wirkung |
|---|---|
| `appServiceSku` | Consumption vs. Premium (kein Cold Start, mehr RAM/CPU) |
| `functionScaleLimit` | Maximale parallele Instanzen |
| `maxConcurrentCalls` (`host.json`) | Parallel verarbeitete Nachrichten je Instanz |
| Priorisierte Queues | Drei getrennte Trigger für unabhängige Lastpfade |
| `maxPageSize` in der Connection, `MaxBatchSize` in der Activity | Seitengröße beim Abruf |
| `Order` und `Priority` am Job | Reihenfolge und Priorität |

> **Service Bus Basic**
>
> Die SKU Basic unterstützt keine Topics, Sessions, Partitionierung und keine Duplicate
> Detection. Die Architektur nutzt ausschließlich Queues. Ein Wechsel auf Topics oder Sessions
> würde ein SKU-Upgrade und Code-Änderungen erfordern.



## Abgrenzung

- Keine eigene Benutzeroberfläche. Konfiguration erfolgt in Table Storage, Diagnose über
  HTTP-Endpunkte und MCP.
- Kein ETL- oder Data-Warehouse-Werkzeug für Massenläufe, sondern inkrementelle Synchronisation.
- Transaktionen und fachliche Konsistenz bleiben in den angebundenen Systemen.