Skip to content

docs: add SDK development guide, master image guide and extend getting started #123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SirHerr merged 6 commits into from
Oct 8, 2026
Merged

docs: add SDK development guide, master image guide and extend getting started #123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0994980
docs(user): add guide on developing an analysis with the SDK
SirHerr Oct 8, 2026
d68184b
docs(user): add guide on requesting a master image
SirHerr Oct 8, 2026
1135cd6
docs(node): highlight list and read permissions required for S3 bucke…
SirHerr Oct 8, 2026
3cac1f0
docs(team): move Hammam Abu Attieh to alumni
SirHerr Oct 8, 2026
c08ef6a
docs(getting-started): extend architecture and introduction
SirHerr Oct 8, 2026
0ade1ac
docs(getting-started): complete glossary
SirHerr Oct 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/.vitepress/routes/sidebar/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ export const sidebarRoutes = [
{text: 'Architecture', link: '/architecture'},
{text: 'Components', link: '/components'},
{text: 'Guides', link: '/guides'},
{text: 'Glossar', link: '/glossar'},
{text: 'Glossary', link: '/glossar'},
{text: 'FAQs', base:'/guide/faqs', collapsed: true, items: faqsRoutes},
]
},
Expand Down
2 changes: 2 additions & 0 deletions src/.vitepress/routes/sidebar/user.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ export const userRoutes = [
text: 'Concepts/Tutorials',
collapsed: true,
items: [
{ text: 'Developing with the SDK', link: '/sdk-how-to' },
{
text: 'Analysis Coding',
collapsed: true,
Expand Down Expand Up @@ -57,6 +58,7 @@ export const userRoutes = [
]
},
{ text: 'FHIR Queries', link: '/fhir-query' },
{ text: 'Master Images', link: '/master-images' },
// {text: 'Homomorphic Encryption', link: '/homomorphic-encryption'},
]
},
Expand Down
16 changes: 8 additions & 8 deletions src/components/VPTeam.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,14 +74,6 @@ const members = [
{ icon: 'github', link: 'https://github.com/pbrassel' },
],
},
{
avatar: 'https://github.com/AbuAttieh.png',
name: 'Hammam Abu Attieh',
title: 'Privacy Engineer ',
links: [
{ icon: 'github', link: 'https://github.com/AbuAttieh' },
],
},
{
avatar: 'https://github.com/mhalilovic.png',
name: 'Mehmed Halilovic',
Expand Down Expand Up @@ -181,6 +173,14 @@ const alumni = [
{ icon: 'github', link: 'https://github.com/raphaelre' },
],
},
{
avatar: 'https://github.com/AbuAttieh.png',
name: 'Hammam Abu Attieh',
title: 'Privacy Engineer ',
links: [
{ icon: 'github', link: 'https://github.com/AbuAttieh' },
],
},
];

const pi = [
Expand Down
90 changes: 88 additions & 2 deletions src/getting-started/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,93 @@ const image = {

# Architecture

This graphic is intended to provide a rough overview of the FLAME execution flow.
On the next page more detailed information about the individual services is given.
FLAME consists of two parts: one central **Hub** and one **Node** at every participating site. The Hub coordinates,
the Nodes compute. Patient data stays at the site, only analysis code travels to the data and only aggregated results
travel back.

<VPImage :image="image"></VPImage>

The graphic gives a rough overview of the execution flow of an analysis. The individual services are listed on the
[Components](./components) page.

## Hub and Node

| | Hub | Node |
|---|---|---|
| Runs | once, centrally | once per site (hospital, university, ...) |
| Purpose | coordination | execution on local data |
| Holds | users, projects, analysis code, analysis images, results | the site's data stores and running analyses |
| Sees patient data | no | yes, inside the site only |
| Used by | researchers and administrators | node administrators and data stewards |

### Hub

The Hub is the single place researchers work with. Its services:

* **User Interface** to create projects and analyses, review them and download results.
* **Core** as the main backend, managing all resources and triggering commands and events.
* **Authentication and authorization** (Authup), organized in one *realm* per organization.
* **Analysis building**, which combines the approved code with a master image into a container image.
* **Container image registry** (Harbor) with a separate, private project for every node.
* **Message Broker**, which relays the messages nodes send to each other.
* **Storage** for code, intermediate results and final results.

### Node

A Node is installed on a Kubernetes cluster inside the network of a site. Its services:

* **Node UI** to configure data stores and to start, stop and monitor analyses.
* **Hub API Adapter**, the backend of the Node UI and the connection to the Hub.
* **Pod Orchestration**, which starts every analysis in its own isolated pod.
* **Data access through an API gateway** (Kong), which exposes exactly the data stores of a project to its analyses.
* **Message Broker** and **Result Service**, the node side of the communication with other nodes and the Hub.

## Lifecycle of an analysis

1. **Project:** a researcher creates a project in the Hub and selects the nodes that should take part. Every selected
node approves or rejects the project.
2. **Data stores:** at every approving site, an administrator or data steward connects the requested data (a FHIR
server or an S3 bucket) to the project as a data store.
3. **Analysis:** the researcher creates an analysis within the project, uploads the code and selects a master image
with the required dependencies.
4. **Review:** the administrator of every node can download and read the code, and approves or rejects the analysis.
5. **Build and distribution:** after the approvals, the Hub builds one container image from master image and code and
pushes it into the registry project of each node.
6. **Execution:** every node pulls its image. The node administrator starts the analysis in the Node UI. The analysis
runs in an isolated pod and can only reach the data stores of its own project.
7. **Aggregation:** the analyzing nodes send their results to the node with the aggregator role, which combines them.
For iterative methods such as federated learning this repeats over several rounds.
8. **Results:** the aggregator submits the final result to the Hub storage, where the researcher downloads it.

The same steps from the perspective of each role are described in the [User](../guide/user/index) and
[Admin](../guide/admin/index) guides.

## Communication

* **Nodes connect to the Hub, never the other way round.** All connections are initiated by the Node as outbound
HTTPS. A Node does not have to be reachable from the internet.
* **Nodes do not talk to each other directly.** Messages and intermediate results are relayed through the Hub.
* **What is relayed is encrypted end to end.** Messages and intermediate results are encrypted for the receiving
nodes with the node key pairs, so the Hub cannot read them.
* **Analyses are isolated.** An analysis container has no internet access and no access to other services of the
Node. It only reaches its project's data, the message broker and the result service through a dedicated proxy.

Details are documented in [Security & Operations](../guide/deployment/node-security).

## Where data lives

| Data | Location | Leaves the site |
|---|---|---|
| Patient data (FHIR resources, files) | data stores of the site | no |
| Analysis code | Hub storage, and inside the analysis image | yes, it is distributed to the nodes |
| Analysis image | Hub registry, pulled by the nodes | yes, it is distributed to the nodes |
| Messages and intermediate results | relayed and stored by the Hub, end-to-end encrypted | yes, readable only by the receiving nodes |
| Local intermediate results and checkpoints | storage of the node | no |
| Final results | Hub storage | yes, downloadable by the researcher |

Because final results leave the federation, an analysis must only return aggregated, non-identifying values. This is
what the code review by the node administrators is for.

## Deployment

Hub and Node are both deployed with Helm charts on Kubernetes. See the [Deployment guide](../guide/deployment/index).
67 changes: 46 additions & 21 deletions src/getting-started/glossar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,47 @@
# Glossary


| Term | Explanation |
|:--------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| Aggregation protocol | Algorithm code how final/online results are computed|
| Analysis | Docker containers containing algorithm, analysis logic and software dependencies |
| Data discovery | Pre-analysis to verify biases, schemas or any other unexpected behavior by sites |
| Federated Learning | Parallel execution of analysis code at multiple sites, at the same time with a global result aggregation |
| FHIR | Fast Healthcare Interoperability Resources |
| FHIR Core | Common data schema developed by MII to be fulfilled by each DIC |
| Final results | Results achieved by aggregator, can be encrypted project specific |
| FLAME | Federated Learning and Analysis In Medicine |
| Hub | All service components centrally hosted and operated |
| UI | User Interface |
| Paillier - key | This is the key to a homomorphic encryption system to additionally secure the calculated data inside the analysis |
| Proposal | A Proposal is an organizational unit in FLAME, which represents the collaboration between different participants in regard to a specific research or analysis project. It contains an initial risk assessment as well as a high level description of the requested data. |
| Registry | Service to distribute analysis |
| Result inspection | Before results are returned these should be approved by sites to not contain unauthorized information |
| RSA - key | This is the key to a homomorphic encryption system to secure the analysis from external influences |
| Nodes | Hospitals hosting a node to provide analysis controlled and secure access to patient data |


| Term | Explanation |
|:---|:---|
| Aggregation protocol | Algorithm code how final/online results are computed |
| Aggregator | Node of an analysis that combines the results of the analyzers, decides in iterative analyses whether another round is needed, and submits the final result to the Hub |
| Analysis | Docker containers containing algorithm, analysis logic and software dependencies |
| Analyzer | Node of an analysis that executes the analysis code on its local data and sends its result to the aggregator |
| Authup | Identity and access management service of the Hub, managing realms, users, roles, clients and permissions |
| Bucket | Storage location for files in an S3 object store. A bucket is connected to a project as a data store |
| Checkpoint | Saved state of an analysis in the local storage of a node, from which a later analysis of the same project can resume |
| Client | Technical account for automated access to the Hub API, which cannot log in to the user interface (formerly *robot*) |
| Core SDK | Python library (`FlameCoreSDK`) through which analysis code accesses data, exchanges messages with other nodes and submits results |
| Data discovery | Pre-analysis to verify biases, schemas or any other unexpected behavior by sites |
| Data steward | Role at a node that may create and modify data stores, but not start or stop analyses |
| Data store | Configuration at a node that maps a project to a data source of the site, either a FHIR server or an S3 bucket |
| DIC | Data Integration Center. Unit at a university hospital of the MII that provides clinical data for research |
| Differential privacy | Technique that adds calibrated noise to a result, so that it reveals less about individual persons |
| Federated Learning | Parallel execution of analysis code at multiple sites, at the same time with a global result aggregation |
| FHIR | Fast Healthcare Interoperability Resources |
| FHIR Core | Common data schema developed by MII to be fulfilled by each DIC |
| Final results | Results achieved by aggregator, can be encrypted project specific |
| FLAME | Federated Learning and Analysis In Medicine |
| Harbor | Container image registry of the Hub. Analysis images are distributed to the nodes through a separate project per node |
| Homomorphic encryption | Encryption scheme that allows computing on encrypted values without decrypting them |
| Hub | All service components centrally hosted and operated |
| Identity provider | External login service (OIDC) that can be connected to a realm, so users log in with their existing account |
| Intermediate results | Results stored during an analysis, either locally on a node or on the Hub, encrypted for the receiving nodes |
| Kong | API gateway of a node through which an analysis accesses the data stores of its project |
| Master image | Base container image providing the runtime and software dependencies on which an analysis is built |
| Message broker | Service that relays messages between the nodes of an analysis through the Hub |
| MII | Medical Informatics Initiative. German funding program in which PrivateAIM is a project |
| Nodes | Hospitals hosting a node to provide analysis controlled and secure access to patient data |
| Paillier - key | This is the key to a homomorphic encryption system to additionally secure the calculated data inside the analysis |
| Permission | Predefined action in the Hub that is granted to users through roles |
| PrivateAIM | Project within the MII that develops the FLAME platform |
| Project | Current name of a proposal in the Hub user interface, see *Proposal* |
| Proposal | A Proposal is an organizational unit in FLAME, which represents the collaboration between different participants in regard to a specific research or analysis project. It contains an initial risk assessment as well as a high level description of the requested data. |
| Proxy | Node of an analysis without data that pre-aggregates the results of its assigned analyzers, so the aggregator never sees the result of a single node (`ProxyModel`) |
| Realm | Administrative namespace in the Hub representing one organization, with its own users, roles, identity providers and nodes |
| Registry | Service to distribute analysis |
| Result inspection | Before results are returned these should be approved by sites to not contain unauthorized information |
| Role | Named set of permissions that is assigned to users |
| RSA - key | This is the key to a homomorphic encryption system to secure the analysis from external influences |
| S3 | Object storage interface. FLAME reads files such as CSV or VCF from S3 buckets |
| Star pattern | Analysis topology in which every analyzer reports to one aggregator (`StarModel`) |
| UI | User Interface |
Loading
Loading