Add PLUGIN/applicatie.md

dkapitan · dkapitan · commit ee1fc5d599b6 · 2026-01-19T18:15:01.000+01:00
diff --git a/docs/implementaties/PLUGIN/applicatie.md b/docs/implementaties/PLUGIN/applicatie.md
@@ -1,73 +1,115 @@
-# Architectuur
+# Applicatie componenten voor decentrale verwerking
 
-Om een federatieve infrastructuur mogelijk te maken, zijn er op technisch vlak twee vereisten: 
+## Applicatiecomponenten van PLUGIN
 
-* Software voor het federatief toegankelijk maken van data
-* De data op de verschillende bronnen dient interoperabel te zijn.
+![](./plugin-overzicht.drawio.svg)
 
-PLUGIN maakt gebruik van **[Vantage6](https://vantage6.ai/)** om data te ontsluiten voor federatief gebruik. De data zelf wordt FAIR (en dus interoperabel) gemaakt door middel van **[HL7 FHIR](https://hl7.org/fhir/)**.
+Het datastation (links) en de federated processing hub (rechts) vormen de twee-eenheid van de PLUGIN/vantage6 architectuur. Hieronder wordt de functie van elke component in meer detail beschreven.
 
-## Vantage6
+!!! note "Gedetailleerde beschrijving applicatiecomponenten vantage6"
 
-Vantage6 is een open-source infrastructuur voor het uitvoeren van een breed spectrum aan federatieve algoritmen. Bij ieder data station wordt een Vantage6 node geïnstalleerd. Een centraal Vantage6 server component faciliteert communicatie en bewaart slechts de tussentijdse resultaten, welke niet terug te herleiden zijn naar een patiënt. Vanuit een user interface en een client kunnen bevoegde gebruikers nieuwe analyses en algoritmen starten, welke rechtstreeks worden opgehaald uit een vertrouwde bibliotheek.
+    === "**vantage6 server**"
 
-![PLUGIN architectuur](../../assets/Architectuurplaat-PLUGIN.jpeg)
+        Om communicatie mogelijk te maken tussen de verschillende nodes, slaat de Vantage6 Server informatie op over onder andere de deelnemende organisaties, de beschikbare nodes, en de invoer en resultaten van alle aangemaakte taken in het systeem. Deze informatie wordt opgevraagd door de nodes met behulp van een REST api en websockets, waardoor het niet nodig is binnenkomende poorten te openen op het data station.
 
-### Vantage6 Server
+        Door middel van authenticatie en authorisatie op basis van aan te wijzen rollen wordt bijgehouden welke acties toegestaan zijn voor o.a. gebruikers en nodes.
 
-Om communicatie mogelijk te maken tussen de verschillende nodes, slaat de Vantage6 Server informatie op over onder andere de deelnemende organisaties, de beschikbare nodes, en de invoer en resultaten van alle aangemaakte taken in het systeem. Deze informatie wordt opgevraagd door de nodes met behulp van een REST api en websockets, waardoor het niet nodig is binnenkomende poorten te openen op het data station.
-Door middel van authenticatie en authorisatie op basis van aan te wijzen rollen wordt bijgehouden welke acties toegestaan zijn voor o.a. gebruikers en nodes.
+    === "**vantage6 node**"
 
-### Algoritmen en Bibliotheek
+        De Vantage6 Node voert openstaande taken uit. Hierbij wordt het aangegeven Docker image uit de bibliotheek gehaald en uitgevoerd, en gekoppeld aan een van de vooraf geconfigureerde databronnen. Voor elke taak wordt door middel van configuratie gecontroleerd of het uitvoeren van de Docker image toegestaan is.
 
-Voor een maximale flexibiliteit in het soort uit te voeren taak, wordt in Vantage6 gebruik gemaakt van [Docker images](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/). Een sjabloon-image bevat vereiste logica zoals het verwerken van inputs en terugsturen van resultaten. Deze kan vervolgens worden uitgebreid met de specifieke logica voor de use-case, zoals bijvoorbeeld een federatieve query of een federated learning algoritme. Het Docker image dat hieruit resulteert wordt opgeslagen in een centrale [Docker registry](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-registry/) (een bibliotheek voor Docker images).
+        Om het algoritme uit te voeren start de node op basis van het binnengehaalde Docker image een Docker container op het data station. Communicatie vanuit het algoritme verloopt hierbij altijd via de node naar de server.
 
-### Vantage6 Node
+    === "**Algoritmen en bibliotheek**"
 
-De Vantage6 Node voert openstaande taken uit. Hierbij wordt het aangegeven Docker image uit de bibliotheek gehaald en uitgevoerd, en gekoppeld aan een van de vooraf geconfigureerde databronnen. Voor elke taak wordt door middel van configuratie gecontroleerd of het uitvoeren van de Docker image toegestaan is.
+        Voor een maximale flexibiliteit in het soort uit te voeren taak, wordt in Vantage6 gebruik gemaakt van [Docker images](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/). Een sjabloon-image bevat vereiste logica zoals het verwerken van inputs en terugsturen van resultaten. Deze kan vervolgens worden uitgebreid met de specifieke logica voor de use-case, zoals bijvoorbeeld een federatieve query of een federated learning algoritme. Het Docker image dat hieruit resulteert wordt opgeslagen in een centrale [Docker registry](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-registry/) (een bibliotheek voor Docker images).
 
-Om het algoritme uit te voeren start de node op basis van het binnengehaalde Docker image een Docker container op het data station. Communicatie vanuit het algoritme verloopt hierbij altijd via de node naar de server.
 
-## HL7 FHIR
 
+## Federatief leren met PLUGIN/vantage6
 
+De PLUGIN-architectuur is gebaseerd op vantage6. Het gefedereerd leren van een algoritme omvat een reeks gecoördineerde stappen tussen de onderzoeker, de centrale server en de datastations. Dit proces is ontworpen om de analyse uit te voeren zonder dat de brongegevens de lokale omgeving van het datastation verlaten. Hieronder volgt een detailleerde beschrijving wat elk van de applicatiecomponenten hierin doen.
 
+![](./pht-workflow.png)
 
-## Benodigdheden
+???+ note "**Authenticatie**"
 
-### Juridisch
+    De onderzoeker start het proces door te authenticeren bij de centrale Vantage6-server.
 
-https://www.medicaldataworks.nl/governance
+??? note "**Taak specificatie**"
+    
+    Na succesvolle authenticatie definieert de onderzoeker een taak. Hierbij wordt opgegeven:
+    *   Welk algoritme (Docker-image) gebruikt moet worden.
+    *   Specifieke inputparameters voor de analyse.
+    *   Het aantal iteraties (indien van toepassing, voor machine learning).
+    *   De identiteit van de *Secure Aggregation Server* (SAS), de node die verantwoordelijk is voor het aggregeren van resultaten.
 
+??? note "**Verzending naar nodes**"
+    
+    De centrale server stuurt de taak door naar de betrokken nodes. De SAS (Secure Aggregation Server, een specifieke node) ontvangt het verzoek als eerste.
 
-### Data Station Hardware
+??? note "**Start hoofdalgoritme (SAS)**"
+    
+    De SAS downloadt het Docker-image, start het hoofd-algoritme en orkestreert de subtaken die door de datastations uitgevoerd moeten worden.
 
-PLUGIN verwacht bij voorkeur de volgende hardware-specificaties:
+??? note "**Start subtaken (datastations)**"
+    
+    De datastations ontvangen hun subtaak van de centrale server, downloaden hetzelfde Docker-image en starten het lokale deel van het algoritme. De analyse wordt uitgevoerd op de lokale data.
 
-* ≥ 16 cores, x86/x64 CPU
-* ≥ 56 GB CPU RAM
-* ≥ 360 GB SSD
-* virtualization enabled
-* GPU (optioneel, maar aanbevolen):
-    * CUDA compatible NVIDIA kaart
-    * 16 GB GPU RAM
+??? note "**Verzending lokale resultaten**"
+    
+    Na elke trainingscyclus of analysestap stuurt het algoritme op het datastation de lokale resultaten (bijv. modelgewichten of statistische coëfficiënten) naar de SAS. De brongegevens verlaten het datastation niet.
 
+??? note "**Verificatie en aggregatie**"
+    
+    De SAS verifieert de resultaten, extraheert de metadata en voegt de resultaten van alle datastations samen tot een geaggregeerd tussenmodel. Dit voltooit één iteratie.
 
-Specificaties zijn echter sterk afhankelijk van de uit te voeren algoritmen.
+??? note "**Vervolg-iteraties**"
+    
+    Voor vervolgstappen vragen de datastations de geaggregeerde resultaten van de vorige ronde op bij de SAS om hun lokale modellen verder te trainen. Deze cyclus herhaalt zich totdat het model convergeert of het gewenste aantal iteraties is bereikt.
 
-### Netwerk
+??? note "**Afronding**"
+    
+    De SAS informeert de onderzoeker dat de taak is voltooid. De onderzoeker kan vervolgens het finale, globale model downloaden van de server. Gedurende het proces heeft niemand, ook de onderzoeker niet, toegang tot de tussenresultaten, wat de veiligheid waarborgt.
 
-* ≥ 100Mbit ethernet
-* Poort 443/TCP (https) open voor **uitgaand** verkeer naar de server
-* Een Publiek IP-adres voor whitelisting bij de server
+## PLUGIN en de European Interoperability Reference Architecture (EIRA)
 
-### Software
+De architectuur van PLUGIN, gebaseerd op de principes van de Personal Health Train en Vantage6, kan worden beschreven aan de hand van de **European Interoperability Reference Architecture (EIRA)**. EIRA biedt een raamwerk om interoperabele architecturen te ontwerpen door herbruikbare *Architectural Building Blocks (ABBs)* te identificeren.
 
-* Besturingssysteem: Ubuntu 22.04+, Windows 10 of hoger, macOS 13.x of hoger
-* Docker of Docker Desktop
-* Python versie 3.10+
+Hoewel een gedetailleerde mapping naar specifieke EIRA ABB's een technische oefening is (vaak vastgelegd in een Archimate-model), kunnen we de componenten van PLUGIN conceptueel positioneren binnen de EIRA-gedachte. De architectuur is opgebouwd uit logische componenten die elk een specifieke rol vervullen, wat aansluit bij de EIRA-visie. De belangrijkste componenten, beschouwd als ABBs, zijn hieronder weergegeven.
+
+
+!!! note "PLUGIN in termen van EIRA architectural building blocks"
+
+    === "**Processing hub**"
+    
+        Fungeert als een intermediair voor communicatie, beheert metadata van taken en orkestreert de interacties. Dit kan worden gezien als een combinatie van EIRA ABBs gerelateerd aan *Message Exchange*, *Service Registry* en *Process Control*.
+
+    === "**Datastation**"
+        
+        De component binnen de jurisdictie van de datahouder (bv. een ziekenhuis). Het voorziet in de rekenkracht voor de lokale analyse en waarborgt dat data de eigen omgeving niet verlaat. Dit komt overeen met EIRA ABBs voor *Secure Data Processing* en *Service Consumption*.
+
+    === "**Secure Aggregation Server (SAS)**"
+    
+        Een gespecialiseerde node die verantwoordelijk is voor het veilig aggregeren van de lokale resultaten. Dit is een specifieke invulling van een *Data Processing* en *Security* ABB.
+
+    === "**Algoritme (Docker Image)**"
+    
+        Het "treintje" dat de analyse definieert. Het is een zelfstandige, uitvoerbare component die de logica, het model en de API bevat. Dit sluit aan bij het idee van een *Business Logic Component* of *Application Service* in EIRA.
+
+    === "**Beveiligde Communicatiekanalen**"
+    
+        De infrastructuur die veilige data-uitwisseling (van geaggregeerde resultaten, niet brongegevens) mogelijk maakt. Dit valt onder EIRA ABBs zoals *Secure Communication* en *Network Infrastructure*.
+
+Door de architectuur op deze manier in componenten op te delen, wordt een modulaire en interoperabele opzet gerealiseerd die in lijn is met de principes van EIRA voor het bouwen van grensoverschrijdende en sector-overstijgende digitale diensten.
+
+
+## PLUGIN en de composable data stack
+
+![](./datastation-eira.png)
+
+TO DO: uitleggen hoe al deze componenten eigenlijk een-op-een te vertalen zijn naar de moderne lakehouse architectuur.
 
-## Data
 
 
 
diff --git a/docs/implementaties/PLUGIN/datastation-eira.png b/docs/implementaties/PLUGIN/datastation-eira.png
diff --git a/docs/implementaties/PLUGIN/index.md b/docs/implementaties/PLUGIN/index.md
@@ -16,7 +16,7 @@ De PLUGIN infrastructuur implementeert verschillende componenten zoals in onders
     | PLUGIN-ML | gefedereerd leren |
     | PLUGIN-Hub | data pooling |
     | vantage6 server | centrale processing hub waarop gebruikers, organizaties, samenwerkingsverbanden taken en resultaten worden beheerd en georchestreerd |
-    | vantage6 UI | webapplicatie waarmee gebruikers kunnen interacteren met de serve |
+    | vantage6 UI | webapplicatie waarmee gebruikers kunnen interacteren met de server |
     | vantage6 API | programmatische aansturing van de server, incl. Python client en R client |
     | Docker registry | containers die zijn geautoriseerd om decentraal op de datastations uit te voeren |
     | Algorithm store | de metadata over de (algoritme) containers, inclusief ondersteuning van goedkeuringsproces |
@@ -25,8 +25,6 @@ De PLUGIN infrastructuur implementeert verschillende componenten zoals in onders
     | PLUGIN-Lake | Lakehouse voor serverless opslag en ETL transformaties op het datastation |
 
 
-
-
 ??? info "Externe documentatie"
 
     - [PLUGIN programma website](https://plugin.healthcare/)
diff --git a/docs/implementaties/PLUGIN/informatie.md b/docs/implementaties/PLUGIN/informatie.md
@@ -34,8 +34,6 @@ In de doorontwkkeling van PLUGIN is voorzien dat andere informatiemodellen (OMOP
 
 ## DHD thesauri als basis voor semantische interoperabiliteit
 
-Voor semantische interoperabiliteit leunt PLUGIN sterk op de expertise en standaarden van DHD (Dutch Hospital Data), en specifiek de [Diagnose- en Verrichtingenthesaurus](https://www.dhd.nl/producten-diensten/registratie-data/oplossingen-voor-registratievraagstukken). Deze thesauri zijn zijn de landelijke standaarden voor de registratie van medische diagnosen respectievelijk verrichtingen. De thesauri bestaan uit lijsten met uniforme termen die worden ingeladen in het epd. Hierdoor kunnen artsen en andere zorgprofessionals de termen aan de bron vastleggen in de taal die zij in de praktijk gebruiken. Elke twee maanden verschijnen nieuwe versies, zodat de lijsten altijd actueel zijn. Gebruikers kunnen verzoeken voor wijzigingen bij ons indienen.
-
-Omdat iedereen volgens dezelfde standaarden registreert, kan de informatie soepel worden uitgewisseld en voor meerdere doeleinden worden gebruikt. De termen leiden automatisch af naar DBC-codes, ICD-10-codes, conciliumcodes (opleidingscodes) en het internationale terminologiestelsel SNOMED. Door deze thesaurus te gebruiken, zorgt PLUGIN ervoor dat analyses die over verschillende ziekenhuizen heen worden uitgevoerd, gebaseerd zijn op data met een consistente en gedeelde betekenis.
+Voor semantische interoperabiliteit leunt PLUGIN sterk op de expertise en standaarden van DHD (Dutch Hospital Data), en specifiek de [Diagnose- en Verrichtingenthesaurus](https://www.dhd.nl/producten-diensten/registratie-data/oplossingen-voor-registratievraagstukken). Deze thesauri zijn zijn de landelijke standaarden voor de registratie van medische diagnosen respectievelijk verrichtingen. De thesauri bestaan uit lijsten met uniforme termen die worden ingeladen in het epd. Hierdoor kunnen artsen en andere zorgprofessionals de termen aan de bron vastleggen in de taal die zij in de praktijk gebruiken. Elke twee maanden verschijnen nieuwe versies, zodat de lijsten altijd actueel zijn. Door deze thesauri te gebruiken, zorgt PLUGIN ervoor dat analyses die over verschillende ziekenhuizen heen worden uitgevoerd, gebaseerd zijn op data met een consistente en gedeelde betekenis. Zo kunnen concepten automatisch worden afgeleid naar DBC-codes, ICD-10-codes, conciliumcodes (opleidingscodes) en het internationale terminologiestelsel SNOMED.
 
 In de doorontwikkeling van PLUGIN wordt gedacht om de thesauri uit te breiden met de [SSSOM-methode](https://mapping-commons.github.io/sssom/). Daarmee kunnen niet alleen mappings tussen verschillende codestelsel gemaakt worden, maar kan ook aangegeven worden of een mapping een `exactMatch`, een `broadMatch` of een `narrowMatch` is. Dit is van waarde omdat bijvoorbeeld in de huisartsen zorg veel bredere diagnosen worden geregistreerd zoals epilepsie, terwijl in een ziekenhuis of UMC in meer detail de diagnose wordt gecodeerd, bijvoorbeeld focale epilepsie.
diff --git a/docs/implementaties/PLUGIN/infrastructuur.md b/docs/implementaties/PLUGIN/infrastructuur.md
@@ -0,0 +1,26 @@
+### Data Station Hardware
+
+PLUGIN verwacht bij voorkeur de volgende hardware-specificaties:
+
+* ≥ 16 cores, x86/x64 CPU
+* ≥ 56 GB CPU RAM
+* ≥ 360 GB SSD
+* virtualization enabled
+* GPU (optioneel, maar aanbevolen):
+    * CUDA compatible NVIDIA kaart
+    * 16 GB GPU RAM
+
+
+Specificaties zijn echter sterk afhankelijk van de uit te voeren algoritmen.
+
+### Netwerk
+
+* ≥ 100Mbit ethernet
+* Poort 443/TCP (https) open voor **uitgaand** verkeer naar de server
+* Een Publiek IP-adres voor whitelisting bij de server
+
+### Software
+
+* Besturingssysteem: Ubuntu 22.04+, Windows 10 of hoger, macOS 13.x of hoger
+* Docker of Docker Desktop
+* Python versie 3.10+
diff --git a/docs/implementaties/PLUGIN/pht-workflow.png b/docs/implementaties/PLUGIN/pht-workflow.png
diff --git a/docs/implementaties/PLUGIN/proces.md b/docs/implementaties/PLUGIN/proces.md
@@ -17,7 +17,7 @@ Om een federatief proces te starten, moet eerst een samenwerkingsverband worden
 *   **Taak (Task):** Een specifieke opdracht, zoals het trainen van een model of het uitvoeren van een analyse, die naar een of meerdere nodes wordt gestuurd.
 *   **Rol (Role) en Regel (Rule):** Definiëren de permissies van een gebruiker.
 
-De **vantage6 Server** beheert deze entiteiten en zorgt voor veilige communicatie en correcte autorisatie, in lijn met de governance-eisen van de dataspace.
+De **vantage6 Server** beheert deze entiteiten en zorgt voor veilige communicatie en correcte autorisatie, in lijn met de governance-eisen van de dataspace. Medical Dataworks heeft afgelopen jaren veel ervaring opgedaan met het opzetten van dergelijke samenwerkingsverbanden en heeft hiertoe standaard [overeenkomsten en governance documenten](https://www.medicaldataworks.nl/governance) opgesteld en open source beschikbaar gesteld.
 
 ## Uitvoeren van een federatieve taak
 
