# medical-informatics-platform/platform-backend architecture

> Architecture diagram of the GitHub repository medical-informatics-platform/platform-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/medical-informatics-platform/platform-backend
- Repository: https://github.com/medical-informatics-platform/platform-backend

## Overview

#### Purpose and Runtime
This repository is the Java backend for the MIP platform. It is a Spring-based HTTP service packaged as a Docker image, configured for PostgreSQL persistence, Keycloak authentication, and an external Exaflow server. Application bootstrap is `src/main/java/hbp/mip/MIPApplication.java`; runtime defaults and environment-variable binding are in `src/main/resources/application.yml` and `config/application.tmpl`.

#### API Layer
REST-facing components are organized by domain:
- Algorithms: `src/main/java/hbp/mip/algorithm/AlgorithmsAPI.java`
- Data models: `src/main/java/hbp/mip/datamodel/DataModelAPI.java`
- Experiments: `src/main/java/hbp/mip/experiment/ExperimentAPI.java`
- Active user context: `src/main/java/hbp/mip/user/ActiveUserAPI.java`

These APIs receive requests, use DTOs as boundary contracts, and delegate business work to services rather than directly managing persistence or remote calls.

#### Experiment Orchestration
Experiments are the central persisted execution domain. `src/main/java/hbp/mip/experiment/ExperimentService.java` coordinates experiment creation/retrieval and execution-oriented behavior, while `src/main/java/hbp/mip/experiment/ExperimentDAO.java` and `src/main/java/hbp/mip/experiment/ExperimentRepository.java` separate data access from service logic. Execution payloads are represented by `src/main/java/hbp/mip/experiment/ExperimentExecutionDTO.java`.

The principal flow is API request → experiment service → repository/DAO and, where execution is required, the configured Exaflow endpoint.

#### Algorithm and Data-Model Catalogs
Algorithm requests/specifications are handled through `src/main/java/hbp/mip/algorithm/AlgorithmService.java`, `src/main/java/hbp/mip/algorithm/AlgorithmsSpecs.java`, and DTOs in the same package. Data-model access is similarly isolated in `src/main/java/hbp/mip/datamodel/DataModelService.java` and `src/main/java/hbp/mip/datamodel/DataModelDTO.java`.

These components form the input-definition boundary for experiments: algorithm specifications and data-model metadata are resolved before or alongside experiment execution.

#### Identity and Authorization Boundary
Security configuration and authentication integration reside in `src/main/java/hbp/mip/configurations/SecurityConfiguration.java`, `src/main/java/hbp/mip/configurations/AuthenticationEventListener.java`, and `src/main/java/hbp/mip/configurations/SpaRedirectAuthenticationSuccessHandler.java`. Keycloak is the external identity provider; its URL, realm, client ID, and secret are supplied at deployment time.

User identity is converted into platform-level user state through `src/main/java/hbp/mip/user/ActiveUserService.java`, `src/main/java/hbp/mip/user/UserRepository.java`, and claim helpers in `src/main/java/hbp/mip/utils/ClaimUtils.java`. Authentication can be disabled for development.

#### Persistence and Schema
PostgreSQL is required in both development and container deployments. Persistence wiring is centralized in `src/main/java/hbp/mip/configurations/PersistenceConfiguration.java`; initial schema creation is versioned in `src/main/resources/db/migration/V1__InitialSchema.sql`. Repository/DAO pairs in the experiment and user domains provide the persistence boundary.

#### Operational Boundaries
The service is containerized by `Dockerfile`. Logging is configured through `src/main/resources/log4j2.yml`; log levels are environment-controlled. API documentation configuration is located at `src/main/java/hbp/mip/configurations/OpenApiConfig.java`. Cross-cutting request failures are normalized by `src/main/java/hbp/mip/utils/ControllerExceptionHandler.java`.

CI includes image publishing and security scanning workflows under `.github/workflows/publish_images.yml`, `.github/workflows/sast.yml`, and `.github/workflows/container-scan.yml`.

Main entry points: [`src/main/java/hbp/mip/experiment/ExperimentService.java`](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/experiment/ExperimentService.java) (Experiment Service), [`src/main/java/hbp/mip/MIPApplication.java`](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/MIPApplication.java) (MIP Application), [`src/main/java/hbp/mip/configurations/SecurityConfiguration.java`](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/configurations/SecurityConfiguration.java) (Security Configuration), [`src/main/resources/application.yml`](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/resources/application.yml) (Runtime Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_algorithm_api["Algorithms API<br/>REST controller<br/>[AlgorithmsAPI.java]"]
  node_datamodel_api["Data Models API<br/>REST controller<br/>[DataModelAPI.java]"]
  node_experiment_api["Experiments API<br/>REST controller<br/>[ExperimentAPI.java]"]
  node_active_user_api["Active User API<br/>REST controller<br/>[ActiveUserAPI.java]"]
  node_exception_handler["Exception Handler<br/>HTTP error boundary"]
end

subgraph group_core["Application Core"]
  node_application{{"MIP Application<br/>Spring bootstrap"}}
  node_algorithm_service["Algorithm Service<br/>catalog service"]
  node_algorithm_specs["Algorithm Specs<br/>algorithm definitions"]
  node_datamodel_service["Data Model Service<br/>catalog service"]
  node_experiment_service["Experiment Service<br/>orchestration service"]
  node_execution_dto["Execution DTO<br/>execution contract"]
end

subgraph group_security["Identity &amp; Security"]
  node_security_config["Security Configuration<br/>security boundary"]
  node_active_user_service["Active User Service<br/>user context service"]
end

subgraph group_persistence["Persistence"]
  node_experiment_data_access["Experiment DAO &amp; Repository<br/>data access<br/>[ExperimentDAO.java]"]
  node_user_repository["User Repository<br/>data access"]
  node_persistence_config["Persistence Configuration<br/>database wiring"]
  node_schema_migration["Initial Schema<br/>database migration"]
end

subgraph group_external["External Systems"]
  node_keycloak(("Keycloak<br/>identity provider"))
  node_postgresql[("PostgreSQL<br/>relational database")]
  node_exaflow{{"Exaflow Server<br/>execution service"}}
end

subgraph group_operations["Operations"]
  node_runtime_config["Runtime Configuration<br/>deployment configuration<br/>[application.yml]"]
  node_docker_image["Docker Image<br/>container packaging"]
end

node_application -->|"initializes"| node_security_config
node_application -->|"initializes"| node_persistence_config
node_application -->|"loads"| node_runtime_config
node_algorithm_api -->|"delegates"| node_algorithm_service
node_datamodel_api -->|"delegates"| node_datamodel_service
node_experiment_api -->|"delegates"| node_experiment_service
node_active_user_api -->|"delegates"| node_active_user_service
node_algorithm_service -->|"resolves"| node_algorithm_specs
node_experiment_service -->|"resolves algorithm"| node_algorithm_service
node_experiment_service -->|"resolves data model"| node_datamodel_service
node_experiment_service -->|"builds"| node_execution_dto
node_experiment_service -->|"persists and retrieves"| node_experiment_data_access
node_experiment_service -->|"submits execution"| node_exaflow
node_security_config -->|"authenticates via"| node_keycloak
node_security_config -->|"establishes identity"| node_active_user_service
node_active_user_service -->|"loads user state"| node_user_repository
node_persistence_config -->|"connects"| node_postgresql
node_experiment_data_access -->|"reads and writes"| node_postgresql
node_user_repository -->|"reads and writes"| node_postgresql
node_schema_migration -->|"creates schema"| node_postgresql
node_runtime_config -.->|"configures"| node_keycloak
node_runtime_config -.->|"configures endpoint"| node_exaflow
node_docker_image -->|"packages"| node_application
node_exception_handler -.->|"normalizes failures from"| node_experiment_api

click node_application "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/MIPApplication.java"
click node_algorithm_api "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/algorithm/AlgorithmsAPI.java"
click node_datamodel_api "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/datamodel/DataModelAPI.java"
click node_experiment_api "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/experiment/ExperimentAPI.java"
click node_active_user_api "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/user/ActiveUserAPI.java"
click node_exception_handler "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/utils/ControllerExceptionHandler.java"
click node_algorithm_service "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/algorithm/AlgorithmService.java"
click node_algorithm_specs "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/algorithm/AlgorithmsSpecs.java"
click node_datamodel_service "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/datamodel/DataModelService.java"
click node_experiment_service "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/experiment/ExperimentService.java"
click node_execution_dto "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/experiment/ExperimentExecutionDTO.java"
click node_security_config "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/configurations/SecurityConfiguration.java"
click node_active_user_service "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/user/ActiveUserService.java"
click node_experiment_data_access "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/experiment/ExperimentDAO.java"
click node_user_repository "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/user/UserRepository.java"
click node_persistence_config "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/configurations/PersistenceConfiguration.java"
click node_schema_migration "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/resources/db/migration/V1__InitialSchema.sql"
click node_runtime_config "https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/resources/application.yml"
click node_docker_image "https://github.com/medical-informatics-platform/platform-backend/blob/master/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_algorithm_api,node_datamodel_api,node_experiment_api,node_active_user_api,node_exception_handler toneBlue
class node_application,node_algorithm_service,node_algorithm_specs,node_datamodel_service,node_experiment_service,node_execution_dto toneAmber
class node_security_config,node_active_user_service toneMint
class node_experiment_data_access,node_user_repository,node_persistence_config,node_schema_migration toneRose
class node_keycloak,node_postgresql,node_exaflow toneIndigo
class node_runtime_config,node_docker_image toneTeal
```

## Components

### HTTP API

- [Algorithms API](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/algorithm/AlgorithmsAPI.java): REST controller · `src/main/java/hbp/mip/algorithm/AlgorithmsAPI.java`
- [Data Models API](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/datamodel/DataModelAPI.java): REST controller · `src/main/java/hbp/mip/datamodel/DataModelAPI.java`
- [Experiments API](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/experiment/ExperimentAPI.java): REST controller · `src/main/java/hbp/mip/experiment/ExperimentAPI.java`
- [Active User API](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/user/ActiveUserAPI.java): REST controller · `src/main/java/hbp/mip/user/ActiveUserAPI.java`
- [Exception Handler](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/utils/ControllerExceptionHandler.java): HTTP error boundary · `src/main/java/hbp/mip/utils/ControllerExceptionHandler.java`

### Application Core

- [MIP Application](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/MIPApplication.java): Spring bootstrap · `src/main/java/hbp/mip/MIPApplication.java`
- [Algorithm Service](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/algorithm/AlgorithmService.java): catalog service · Resolves algorithm specifications and DTOs. · `src/main/java/hbp/mip/algorithm/AlgorithmService.java`
- [Algorithm Specs](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/algorithm/AlgorithmsSpecs.java): algorithm definitions · `src/main/java/hbp/mip/algorithm/AlgorithmsSpecs.java`
- [Data Model Service](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/datamodel/DataModelService.java): catalog service · `src/main/java/hbp/mip/datamodel/DataModelService.java`
- [Experiment Service](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/experiment/ExperimentService.java): orchestration service · Coordinates persisted experiments and execution requests. · `src/main/java/hbp/mip/experiment/ExperimentService.java`
- [Execution DTO](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/experiment/ExperimentExecutionDTO.java): execution contract · `src/main/java/hbp/mip/experiment/ExperimentExecutionDTO.java`

### Identity & Security

- [Security Configuration](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/configurations/SecurityConfiguration.java): security boundary · Authentication may be disabled for development. · `src/main/java/hbp/mip/configurations/SecurityConfiguration.java`
- [Active User Service](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/user/ActiveUserService.java): user context service · Converts authenticated claims into platform user state. · `src/main/java/hbp/mip/user/ActiveUserService.java`

### Persistence

- [Experiment DAO & Repository](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/experiment/ExperimentDAO.java): data access · `src/main/java/hbp/mip/experiment/ExperimentDAO.java`
- [User Repository](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/user/UserRepository.java): data access · `src/main/java/hbp/mip/user/UserRepository.java`
- [Persistence Configuration](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/java/hbp/mip/configurations/PersistenceConfiguration.java): database wiring · `src/main/java/hbp/mip/configurations/PersistenceConfiguration.java`
- [Initial Schema](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/resources/db/migration/V1__InitialSchema.sql): database migration · `src/main/resources/db/migration/V1__InitialSchema.sql`

### External Systems

- **Keycloak**: identity provider
- **PostgreSQL**: relational database
- **Exaflow Server**: execution service

### Operations

- [Runtime Configuration](https://github.com/medical-informatics-platform/platform-backend/blob/master/src/main/resources/application.yml): deployment configuration · Binds environment settings for database, identity, and Exaflow. · `src/main/resources/application.yml`
- [Docker Image](https://github.com/medical-informatics-platform/platform-backend/blob/master/Dockerfile): container packaging · `Dockerfile`

## Connections

- MIP Application → Security Configuration: initializes
- MIP Application → Persistence Configuration: initializes
- MIP Application → Runtime Configuration: loads
- Algorithms API → Algorithm Service: delegates
- Data Models API → Data Model Service: delegates
- Experiments API → Experiment Service: delegates
- Active User API → Active User Service: delegates
- Algorithm Service → Algorithm Specs: resolves
- Experiment Service → Algorithm Service: resolves algorithm
- Experiment Service → Data Model Service: resolves data model
- Experiment Service → Execution DTO: builds
- Experiment Service → Experiment DAO & Repository: persists and retrieves
- Experiment Service → Exaflow Server: submits execution
- Security Configuration → Keycloak: authenticates via
- Security Configuration → Active User Service: establishes identity
- Active User Service → User Repository: loads user state
- Persistence Configuration → PostgreSQL: connects
- Experiment DAO & Repository → PostgreSQL: reads and writes
- User Repository → PostgreSQL: reads and writes
- Initial Schema → PostgreSQL: creates schema
- Runtime Configuration → Keycloak: configures
- Runtime Configuration → Exaflow Server: configures endpoint
- Docker Image → MIP Application: packages
- Exception Handler → Experiments API: normalizes failures from