HartOMat/docs/workflows/WORKFLOW_MIGRATION_PLAN.md

Workflow Migration Plan

Goal

Bring /workflows to full production parity with the existing legacy render pipeline without breaking the current legacy path at any time.

Current Status

• Phase 1 completed on canonical config storage, preset migration, and legacy-safe runtime extraction.
• Phase 2 completed on backend node registry, node definitions API, and schema-driven editor palette/settings.
• Phase 3 completed: order_line_setup, resolve_template, material_map_resolve, auto_populate_materials, glb_bbox, output_save, and notify are extracted behind the legacy task boundary, validated with targeted backend tests, and covered by workflow executor dispatch tests.
• Phase 4 is partially completed: graph runtime dispatch now treats downstream output_save as the authoritative persistence boundary for still renders, turntable/video renders, and .blend exports, updates node results after persistence, and keeps shadow executions non-authoritative.
• The canonical still bridge path now exposes runtime-backed node settings for template overrides, material resolution, auto-population rules, GLB source selection, output-save artifact filtering, and notify arming, so /workflows can author the real still-render contract instead of relying on hidden legacy defaults.
• Output types now behave as explicit invocation profiles in both API and admin UI: workflow family, artifact kind, and invocation overrides are first-class, and linked workflow compatibility is enforced before dispatch.
• Canonical reference workflows now need to be managed as at least two families, not one mixed graph:
  • CAD Intake
  • Order Rendering

Non-Negotiables

• The legacy render path remains operational throughout the migration.
• No existing output type or order flow may regress while the graph engine is introduced.
• Every node exposed in the workflow editor must have a backend-owned definition and a validated settings schema.
• New workflow definitions use one canonical JSON format.

Canonical Workflow Model

{
  "version": 1,
  "nodes": [
    {
      "id": "resolve_template",
      "step": "resolve_template",
      "params": {},
      "ui": {
        "type": "templateNode",
        "position": { "x": 420, "y": 120 },
        "label": "Resolve Template"
      }
    }
  ],
  "edges": [
    { "from": "setup", "to": "resolve_template" }
  ]
}

Notes:

• step and params are the backend-owned runtime model.
• ui is editor-only metadata and must not change runtime semantics.
• edges are mandatory for graph persistence and validation.

Architecture Direction

• Workflow nodes are orchestration wrappers, not the canonical implementation unit.
• The canonical implementation unit is a backend-owned production module with typed inputs, outputs, defaults, and execution semantics.
• Workflow definitions answer "what runs"; output types answer "which productized invocation profile of that workflow is offered".
• Workflow authoring remains split by family:
  • cad_file
  • order_line
• The detailed target model is captured in docs/workflows/NODE_BASED_PRODUCTION_ARCHITECTURE.md.

Phases

Phase 1: Canonical Model and Migration Base

• Finalize canonical workflow schema.
• Align frontend API types with backend schema.
• Add compatibility migration from preset configs to canonical DAG configs.
• Keep legacy dispatch as default.

Phase 2: Node Registry

• Introduce a backend node registry as the single source of truth.
• Define labels, categories, descriptions, settings schemas, defaults, input contracts, and output contracts for every node.
• Expose node definitions over API for the editor.

Phase 3: Extract Missing Legacy Steps

• Move inline legacy pipeline logic into explicit node executors/services.
• Required parity nodes:
  • order_line_setup
  • resolve_template
  • material_map_resolve
  • auto_populate_materials
  • glb_bbox
  • output_save
  • notify
• Optional but planned:
  • threejs_render

Phase 4: Graph Runtime

• Introduce WorkflowContext and node-by-node execution with persistent run state.
• Support node outputs and artifact handoff across edges.
• Keep legacy, graph, and shadow execution modes.
• Current slice: graph dispatch executes extracted bridge nodes for order-line setup, template/material resolution, auto-material population, and bounding-box resolution before queueing render/export tasks.
• Current slice completed: still-render graphs, turntable/video graphs, and .blend export graphs with downstream output_save now disable task-level self-publish, persist authoritative output/media metadata through shared runtime services, and write the result back into WorkflowNodeResult.
• Next Phase 4 slice: extend the same authoritative output_save contract to any remaining legacy export variants and close the remaining notify/editor parity gaps.

Phase 5: Workflow Editor Parity

• Persist and load nodes, edges, step, params, and ui.
• Render all node settings dynamically from backend schemas.
• Add validation, dry-run, dispatch, and run inspection.
• Organize workflows and node palette by family so the editor reflects the runtime split between cad_file and order_line contexts.
• Current state: right-click insertion, searchable family-aware palettes, auto-align, edge deletion, dry-run, dispatch, and run inspection are already in place; the remaining work is authoring clarity, node organization, and browser-verified end-to-end usability for the non-legacy still graph.
• Do not add further editor-only UX surface before node/module contracts and output-type invocation profiles are stabilized.

Phase 6: Shadow Mode and Rollout

• Run graph executions in parallel to the legacy flow for parity comparison.
• Compare status, outputs, media assets, notifications, and logs.
• Roll out per workflow or output type.

Execution Modes

• legacy: current production path only
• graph: graph runtime is authoritative
• shadow: legacy remains authoritative, graph runs for comparison and observability

Deliverables

• Canonical workflow schema and migration tooling
• Backend node registry and API
• Full editor support for all node settings
• Graph runtime with node-level execution and tracking
• Shadow mode parity checks

Exit Criteria

• A workflow can be authored, validated, executed, and inspected entirely via /workflows.
• Legacy results and graph results match for defined golden cases.
• Legacy fallback is still available after graph rollout.