Architecture

FreshForge is intended to become a neutral workflow core rather than a domain package that imports every FRESH modelling tool. Phase 1 records the first architecture contracts for that direction. Phase 2 adds provisional workflow records, Phase 3 adds provider-aware validation and planning, and Phase 4 adds entry-point adapter discovery without execution.

Intended Dependency Direction

freshforge core
        ^
        |
domain package adapters and provider registrations
        ^
        |
project recipes and instance workflows

Domain packages such as FEMIC, FHOPS, ws3, Modelwright, and Nemora should own their own scientific logic. FreshForge should own shared workflow contracts, validation, execution planning, provenance, and orchestration semantics.

Core Concepts

The Phase 1 vocabulary uses these terms:

workflow: A version-controlled graph specification.
node: A logical workflow step with a stable ID, provider reference, declared inputs, outputs, parameters, dependencies, and diagnostics.
provider: A package-owned implementation surface that can describe and validate a node type. Execution remains deferred.
artifact: A materialized file, dataset, model package, report, or other durable output.
diagnostic: A structured message about invalid configuration, missing providers, unsupported features, uncertainty, or failed validation.
run plan: A pre-execution interpretation of a workflow graph. It should explain node order, provider requirements, expected inputs and outputs, and missing pieces before any expensive or stateful work runs.

Source Format Direction

FreshForge should target text-backed author-authored workflow specs first. YAML is the preferred starting point because it is readable for analysts and suited to nested workflow records. JSON compatibility should remain possible for generated records, tests, and machine interchange.

Phase 1 does not define final syntax. Phase 2 should create the smallest round-trippable record model before adding a complete grammar.

Provider Boundary

FreshForge core should model provider references and diagnostics without directly importing domain packages. Domain packages or thin companion adapters should own scientific logic, runtime dependencies, external executable discovery, and domain-specific validation.

Acceptable future provider locations include native modules inside domain packages, thin companion packages such as freshforge-femic, and local project providers for one-off research workflows.

Phase 4 proves the packaging path with Python entry points under the freshforge.providers group. FreshForge discovers provider factories from installed packages, but it still does not import domain packages directly.

CLI And API Direction

Future CLI command groups should be thin wrappers over Python APIs:

validate: Validate workflow structure, dependencies, provider references, artifacts, and provenance requirements.
plan: Produce a run plan without executing nodes.
inspect: Display workflow metadata, graph structure, provider references, artifacts, or run records.
providers: List registered providers and node types.
run: Execute a validated run plan through provider-owned node implementations.

Current Boundary

Phase 6 implements provisional workflow records, YAML/JSON loading, structural and provider-aware validation, explicit provider registry support, entry-point provider discovery, workflow inspection, provider-aware non-executing planning, and first serial local provider-owned execution.

FreshForge still does not implement cache or checkpoint semantics, parallel execution, remote execution, shell-command nodes, retries, or real ecosystem adapters.

Phase 1 Planning Records

The detailed Phase 1 contracts live in:

planning/phase1_workflow_language_survey.md
planning/phase1_workflow_architecture.md
planning/phase1_provider_boundary_contract.md
planning/phase1_cli_api_boundary.md