Developer Guide – Architecture

This page gives a high-level overview of the internal design.

Intermediate Representation (IR)

All conversions flow through a dataclass-based IR:

  • Workflow → Task → ParameterSpec, RequirementSpec, etc.

  • Versioned JSON schema under wf2wf/schemas/v0.1/wf.json

  • Validation via jsonschema

Why IR?

  • Decouples importers/exporters

  • Enables round-trip testing

  • Central place for metadata handling and loss mapping

Code layout

wf2wf/
  core.py           # IR dataclasses & utils
  importers/        # Format → IR
  exporters/        # IR → Format
  environ.py        # Conda → OCI pipeline
  loss.py           # Loss mapping helpers
  cli.py            # Typer/Click CLI

Adding a new engine

  1. Implement importers/<engine>.py returning a Workflow instance.

  2. Implement exporters/<engine>.py consuming a Workflow.

  3. Register entry-points if distributing externally.

  4. Add tests & docs.