Block Repository Anatomy
Introduction
This document explains the structure and organization of a typical Platforma block repository.
Repository Structure
block-repository/
├── block/ # Main integration package
│ └── block-pack/ # Build output (bundled block)
├── model/ # Data schema definitions and transformations
├── workflow/ # Workflow execution logic (Tengo)
├── ui/ # Frontend components (Vue)
├── software/ # Block's internal bioinformatics tools
├── test/ # Unit tests
├── docs/ # Documentation
├── logos/ # Block and your organization logos
├── .changeset/ # Versioning changes
├── package.json # Root package configuration
├── pnpm-workspace.yaml # Workspace configuration
└── turbo.json # Build pipeline configuration
Core Components
1. Block Package (block/)
The block package serves as the main integration point that references and packages all other components.
Key file: block/package.json
{
"name": "@platforma-open/milaboratories.star-read-mapping",
"version": "1.5.3",
"scripts": {
"build": "rm -rf ./block-pack && block-tools pack",
"prepublishOnly": "block-tools pack && block-tools publish -r 's3://...'"
},
"dependencies": {
"@platforma-open/milaboratories.star-read-mapping.model": "workspace:*",
"@platforma-open/milaboratories.star-read-mapping.ui": "workspace:*",
"@platforma-open/milaboratories.star-read-mapping.workflow": "workspace:*"
},
"block": {
"components": {
"workflow": "@platforma-open/milaboratories.star-read-mapping.workflow/dist/tengo/tpl/main.plj.gz",
"model": "@platforma-open/milaboratories.star-read-mapping.model/dist/model.json",
"ui": "@platforma-open/milaboratories.star-read-mapping.ui/dist"
},
"meta": {
"title": "STAR Read Mapping",
"logo": "file:../logos/block-logo.png",
"description": "Bulk RNA-seq raw sequencing data preprocessing using STAR aligner.",
"tags": ["rna-seq", "qc", "upstream"]
}
}
}
The block section in package.json defines:
- components: References to compiled artifacts from other packages
- meta: Metadata that the Platforma application displays to users in the blocks gallery.
How it's built:
The block package uses the block-tools tool, which is part of the Platforma SDK. This tool handles packaging components into a deployable block.
2. Model Package (model/)
The model package defines the data schema and serves as the bridge between computation and visualization. It orchestrates how data flows from the workflow to the UI, transforming raw workflow results into structured formats that can be used in the block UI.
Key file: model/src/index.ts
import { BlockModel, type PlRef } from '@platforma-sdk/model';
export type BlockArgs = {
ref?: PlRef;
species?: string;
strandness?: string;
title?: string;
};
export const model = BlockModel.create()
.withArgs<BlockArgs>({
species: 'homo-sapiens',
strandness: '0',
})
.output('dataOptions', (ctx) => /* ... */)
.sections([
{ type: 'link', href: '/', label: 'Settings' },
{ type: 'link', href: '/PCA', label: 'Principal Component Analysis' }
])
.done();
How it's built: The model is built using TypeScript tools that generate both code for runtime execution and schema definitions that Platforma can interpret.
3. Workflow Package (workflow/)
The workflow package contains the execution logic written in Tengo, a scripting language used by Platforma for defining computational workflows.
Key files:
workflow/src/main.tpl.tengo: Main workflow implementation
Example structure:
// Simplified workflow example
wf := import("@platforma-sdk/workflow-tengo:workflow")
exec := import("@platforma-sdk/workflow-tengo:exec")
wf.body(func(args) {
// Execute bioinformatics tools and process data
// Return results to the model
})
How it's built:
The workflow is compiled using the pl-tengo tool from the Platforma SDK. Once compiled, the workflow is ready to be executed in the Platforma backend environment when a block is run.
4. UI Package (ui/)
The UI package contains Vue.js components that render the block's interface in the Platforma application. These components provide the visualization layer that users interact with, displaying data processed by the model.
Leverages components from the Platforma SDK for consistent styling and functionality.
Key structure:
ui/src/: Vue components for different block views
How it's built: The UI is built using Vue with TypeScript, compiled with Vite. The compiled assets are bundled and included in the block package.
5. Software Package (software/)
The software package defines the block's internal bioinformatics scripts used either for direct bioinfo analysis or for processing and adapting data between external analysis tools. It enables blocks to run specialized computational algorithms like statistical tools, or data processing scripts.
Key aspects:
- Provides a standardized way to package and execute scientific software
- Supports various languages and runtimes (R, Python, Java, compiled binaries)
- Runs in isolated environments with proper dependency management
- Can be referenced and executed from the workflow
How it's built: The software package is built using tools from the Platforma SDK. Once built, the software is available for execution by workflows in the Platforma backend environment.
The Complete Block Package (block-pack)
The block/block-pack directory contains the compiled and packaged files of a Platforma block, prepared during build for publication to the blocks registry.
- manifest.json: Block package manifest describing all components and metadata
- main.plj.gz: Compiled Tengo workflow (runs on the backend)
- model.json: Bundled model definition
- ui.tgz: Compressed UI components
- Assets: Logos, documentation files, and changelog
The manifest.json file is particularly important as it:
- Identifies the block (organization, name, version)
- References all component files
- Contains metadata for Platforma's marketplace display
- Lists files with sizes and SHA256 hashes for integrity verification
Component Relationships
┌───────────────────────────────────────────────────────────────────────────────┐
│ │
│ block package (Integration Layer) │
│ Components integrated by @platforma-sdk/block-tools │
│ │
└───────────┬─────────────┬──────────────┬─────────────────┬────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐
│ │ │ │ │ │ │ │
│ Model Package │ │ Workflow │ │ UI │ │ Software │
│ (TypeScript) │ │ (Tengo) │ │ (Vue.js) │ │ (R, Python │
│ │ │ │ │ │ │ Java) │
└───────────────┘ └──────────────┘ └──────────────┘ └─────────────┘
│ │ │ │
│ │ │ │
│ ▼ ▼ ▼
└───────────────────────────────────────────────────────┐
▼
┌─────────────┐
│ block-pack │
│(bundled app)│
└─────────────┘
Project Layout
This project uses a monorepo setup, which means that multiple related packages (or projects) are managed together in a single codebase. Instead of having separate repositories for each package, everything lives in one place. It is like one big project folder that contains many smaller projects inside—each with its own purpose, but all working together.
To manage this setup, we use PNPM workspaces. PNPM helps us:
- Organize and maintain consistency: It keeps dependencies for all packages structured and uniform.
- Facilitate code and type sharing: Packages can share code and types. For example, the UI package can utilize types defined in the model package.
- Simplify development: By housing all components of a block within a single folder, development becomes more straightforward.
pnpm-workspace.yaml
packages:
- software
- workflow
- model
- ui
- block
- test
catalog:
'@platforma-sdk/block-tools': ^<Major.minor.patch>
'@platforma-sdk/model': ^<Major.minor.patch>
# ... more dependencies and their versions
Summary
A Platforma block repository is a well-structured monorepo that combines:
- A TypeScript model package defining data structures and orchestrating data flow between workflow and UI
- A Tengo workflow package for execution logic (runs on Platforma backend)
- A Vue.js UI for visualization and user interaction
- Software dependencies for computational tasks, imported and executed in the workflow
- Integration code to package everything together
The build process creates a block-pack, which is the complete, self-contained deployable unit that the Platforma application can load and execute.