Getting Started
Prerequisites
Before you begin, ensure you have the following dependencies installed:
Also, we recommend using Visual Studio Code as an IDE for block development.
What is a Block?
In Platforma, a Block is an application designed to accomplish specific biological tasks, such as analyzing differentially expressed genes or reconstructing B cell lineages. These Blocks are the fundamental components of biomedical research, each contributing uniquely to the overall study.
Understanding how a Block is structured and operates is essential for building effective Platforma applications.
Block structure
A source code of a block consists of several sub-packages, which are managed with PNPM package manager. Each sub-package is defined in a corresponding package.json file. The root package.json file defines the block's itself. The top pnpm-workspace.yaml file defines versions of Platforma SDK dependencies.
A code repository with a block looks like:
├── workflow
│ ├── src/
│ └── package.json
├── model
│ ├── src/
│ └── package.json
├── ui
│ ├── src/
│ └── package.json
├── test
│ ├── src/
│ └── package.json
├── package.json
└── pnpm-workspace.yaml
More details on the block structure are here: Block Repository Anatomy
There are three key block components, which developers create using the Platforma SDK:
Workflow
The workflow represents the bioinformatics pipeline executed on the backend. Platforma provides a straightforward and powerful workflow language that ensures data analysis is both scalable and reproducible.
Arguments of the workflow are the parameters, both required and optional, specified by the user. They typically include input data references (such as files or outputs from other Blocks) and settings for the bioinformatics tools used in the pipeline.
Results of the workflow are the final outputs generated by the bioinformatics pipeline, saved for use in visualizations or for further analysis in subsequent Blocks.
Model
The Block model defines how workflow arguments and results map to the data structures used in the user interface. Bioinformatics pipelines often produce data frames, logs, and files. The model translates these into formats that the UI can use to display tables, progress indicators, and visualizations.
User Interface
The User Interface (UI) is an interactive web application where users set analysis parameters, initiate analyses, and explore results. It is the part of Platforma that users interact with through the desktop app.
The Platforma desktop app is built on the Chromium web browser using Electron.js, making it easy to use modern web development tools to create the Block's UI. See UI SDK for further details.
Block Lifecycle
Blocks are stored in registries as source code. When a user adds a Block to a project, Platforma's desktop app downloads the Block's model and UI to the user’s computer and directs the backend to download the workflow code.
The desktop app renders the UI securely using webcontents view, ensuring the Block's UI only interacts with predefined APIs for saving workflow arguments and retrieving results, without accessing the internet or filesystem.
When the workflow produces new results, the desktop app updates the UI by applying the model’s mapping rules, ensuring the UI reflects the latest data. The code of the model is interpreted in a vanilla JS sandbox environment to ensure isolation.
User interactions with the UI are saved to the backend automatically. When the user runs the workflow, the backend interprets the workflow code, allocating the necessary computational resources.
