Architecture

Anatomy of a BioChef tool

Three pieces ship today: recipes in Git, the Hub CI that signs and publishes, and the BioChef Registry that serves the WebAssembly app.

Shipped today

The path a tool travels

Four stations, left to right. Every artifact is content-addressable; every step is signed.

01 · Source

biochef-recipes

YAML source of truth. Each tool is a biochef.yaml file declaring inputs, runtime, and version.

push

02 · Build

biochef-hub

CI on GitHub Actions: validate, build to WASM, run golden tests, generate SBOM and SLSA, sign with cosign.

publish

03 · Distribute

BioChef Registry

Content-addressable OCI bundles at registry.biochef.app: bundle.json, WASM/JS layers, SBOM, signature.

fetch

04 · Runtime

BioChef web app

Static SPA fetches tools by digest, verifies the signature, and runs them as WebAssembly inside your browser tab.

Every artifact is content-addressable · every step is signed

Deep dive

Component details

Open each card to see what biochef-recipes, the Hub CI, the Registry, and the web app each do.

Recipes & Hub

What it covers

Recipes declare tools/workflows; Hub validates, signs, and bundles them for Registry.

Key behaviors

  • Schema validation against biochef.schema.json; linting; tiny golden tests.
  • Builds with Emscripten/biowasm (WASM) or as a native tarball; generates SBOM and SLSA attestation.
  • Signs the bundle with cosign and pushes to the BioChef Registry, then re-signs index.json.

Practical tips

  • Author YAML in biochef-recipes; run hub validate before opening a PR.
  • Keep inputs/outputs typed; add small fixtures so CI can prove the tool still works.
  • The reusable workflow lives in biochef-hub/.github/workflows/build-recipe.yml.
name: aligner
version: 1.0.0
inputs:
  - id: reads
    type: File
    format: fastq
steps:
  - id: qc
    uses: biochef/qc@1.2.0
  - id: align
    uses: biochef/bwa@0.7
outputs:
  - id: bam
    from: align
Registry & Catalog

What it covers

The BioChef Registry, live at registry.biochef.app, stores signed OCI artifacts (bundle.json + WASM/JS layers + SBOM) and the signed index.json that lists every published tool by digest.

Key behaviors

  • Each tool version is content-addressable: pulled by digest, not by mutable tag.
  • The Hub signs every bundle and the top-level index.json with cosign.
  • WASM and JS assets are served as plain HTTPS so the browser app can stream them.

Practical tips

  • Treat each version as immutable; promote new builds, never overwrite digests.
  • Verify the cosign signature before serving a tool to the browser.
  • Use the signed index.json as the source of truth for what is publishable.
UI & WASM Runtime

What it covers

The BioChef web app, a static React/Webpack SPA, runs every published bioinformatics tool entirely in the browser via WebAssembly. Has a Tools page for single-tool runs and a Workflow page for DAG-style chains.

Key behaviors

  • Loads tools by digest from the BioChef Registry; aioli/biowasm boots them in a Web Worker.
  • Detects input data type (FASTA, FASTQ, packaged FASTQ, amino acids, …) and filters compatible tools.
  • DAG editor re-executes downstream steps on parameter change; recipes can be saved and reloaded.

Practical tips

  • Tools are compiled with Emscripten (3.1.65); rebuild with npm run build-wasm.
  • Outputs stream live to the Output panel; inspect intermediate steps without re-running the whole pipeline.
  • The whole app is static. Host it from any CDN or GitHub Pages.
{
  "runtime": "wasm",
  "tool": "fastq2fasta@1.0.0",
  "verify": true,
  "source": "https://registry.biochef.app/.../sha256:..."
}