How Archify Handles Schema Migration for Workflow Diagrams: A Technical Deep Dive

Archify migrates legacy workflow diagrams from schema v1 to schema v2 through a deterministic, multi-stage pipeline that validates input, probes intrinsic layouts, remaps coordinates via a horizontal rank mapper, and preserves diagram intent while expanding viewBox capacity only when required.

According to the tt-a1i/archify source code, schema migration for workflow diagrams is handled by a sophisticated engine that transforms legacy v1 documents into the modern v2 format without mutating source bytes. The system measures both authored and intrinsic capacities separately, ensuring that visual layouts remain intact while upgrading underlying data structures. This process is implemented across two primary modules: the core migration engine and specialized geometry renderers.

The Core Migration Pipeline

The migration process centers on the migrateWorkflowDocument function defined in archify/migrations/workflow-v2.mjs. This orchestrator manages an eight-stage transformation that maintains idempotency and deterministic output.

Input Validation and Version Detection

Before any transformation occurs, the pipeline validates the input document using the shared schemaDiagnostics validator (lines 28-38). If pre-existing schema errors are detected, migration aborts immediately to prevent corrupt outputs.

The engine then detects the source schema version (lines 39-70). Documents already at schema v2 are re-validated and returned unchanged, while versions other than 1 or 2 trigger a source-schema-version diagnostic error.

Intrinsic Layout Probing

For valid v1 documents, Archify runs two legacy probes to measure the diagram's intrinsic layout without its authored capacity:

• legacyLayoutProbe (lines 40-63): Constructs a minimal v1-compatible workflow containing a single probe node and compiles it to establish baseline measurements.
• legacyRequirementProbe (lines 65-72): Compiles the original workflow after stripping any viewBox to obtain the required viewBox dimensions.

Rank Layout Planning

The geometry planning phase utilizes archify/renderers/workflow/workflow-migration-geometry.mjs to prepare transformation targets:

• intrinsicWorkflow (lines 12-18): Removes the author's viewBox and upgrades the schema structure to v2.
• planningWorkflow (lines 25-53): Drops all authored geometry that might invalidate during pin remapping, preserving only automatic straight relationships.

Both versions are compiled, and if the intrinsic plan fails, the system falls back to the planning projection (lines 88-95 in workflow-v2.mjs).

Coordinate Remapping and Geometry Transformation

Building the Horizontal Rank Mapper

The createHorizontalRankMapper function (lines 65-100) constructs a piecewise-linear function that maps legacy column centers to new rank centers. This mapper preserves relative offsets between elements and extrapolates beyond the original span to accommodate expanded diagrams.

Remapping Explicit Coordinates

Using createMappedWorkflowCandidate (lines 138-144), the engine clones the original workflow, upgrades it to v2, and invokes mapExplicitCoordinates to rewrite absolute positioning data. This process transforms:

• via coordinates on edges
• labelAt positions
• channelX values

The function returns both the migrated document and a comprehensive changedCoordinates audit trail that records each transformation path and value delta.

ViewBox Expansion and Final Validation

After coordinate mapping, the document undergoes compilation again. If the compiler reports a workflow/viewbox-capacity diagnostic, the expandableViewBox helper (lines 30-42) extracts the required dimensions and expands the authored viewBox monotonically. This expansion never shrinks an existing spacious viewBox, ensuring visual content remains accessible.

The migration concludes with final validation, assembling a result object containing:

• Success status flag
• Migrated document
• Old and new required viewBox arrays
• Complete changed coordinates audit trail
• All accumulated diagnostics

CLI Integration and Programmatic Usage

Using the Migration Engine in Node.js

Import the migration function directly for programmatic control:

import { migrateWorkflowDocument } from './archify/migrations/workflow-v2.mjs';
import fs from 'fs';

// Load a legacy workflow (schema v1)
const raw = fs.readFileSync('legacy-workflow.json', 'utf8');
const workflow = JSON.parse(raw);

// Run the migration
const result = migrateWorkflowDocument(workflow);

if (result.ok) {
  console.log('Migration succeeded');
  console.log('Changed coordinates:', result.changedCoordinates);
  fs.writeFileSync('migrated-workflow.json', JSON.stringify(result.document, null, 2));
} else {
  console.error('Migration failed:', result.migrationDiagnostics);
}

Command-Line Interface

The archify.mjs CLI provides atomic file operations that preserve source bytes:

# Migrate a workflow file to schema v2

archify migrate workflow legacy-workflow.json migrated-workflow.json \
  --to-schema 2 --json

The command outputs a structured JSON report:

{
  "ok": true,
  "fromSchemaVersion": 1,
  "toSchemaVersion": 2,
  "changedCoordinates": [
    { "path": "/edges/0/via/0/0", "from": 220, "to": 214 },
    { "path": "/edges/1/labelAt/0", "from": 365, "to": 394 },
    { "path": "/edges/2/channelX", "from": 500, "to": 574 }
  ],
  "oldRequiredViewBox": [720, 652],
  "newRequiredViewBox": [768, 652]
}

Key Architectural Characteristics

Determinism: The rank mapper produces pure functions based solely on column arrays, guaranteeing identical outputs for identical inputs across different environments.

Idempotence: Re-migrating an already-v2 document produces byte-identical files with an empty changedCoordinates array, as verified by the idempotence test in archify/test/workflow-migration.test.mjs.

Capacity-Aware ViewBox: Legacy capacity (display requirements) is measured separately from author-provided viewBox values; the resulting viewBox equals the maximum of both dimensions.

Graceful Diagnostics: All failure modes emit structured diagnostics containing code, subject, evidence, and supportedFixes fields, enabling automated tooling to suggest fixes without breaking CLI contracts.

Safety: Source bytes remain immutable throughout the process; the CLI writes to destination files only after successful validation, with comprehensive test coverage ensuring edge case handling.

Summary

• Validation First: The migrateWorkflowDocument function in archify/migrations/workflow-v2.mjs validates input and detects schema versions before processing.
• Dual Probing: Legacy layout and requirement probes measure intrinsic dimensions separately from authored viewBox values.
• Coordinate Mapping: The createHorizontalRankMapper and mapExplicitCoordinates functions in workflow-migration-geometry.mjs transform absolute positions deterministically.
• Monotonic Expansion: ViewBox sizes only expand to accommodate content, never shrinking existing dimensions.
• Audit Trail: Every coordinate change is tracked with path-specific details in the changedCoordinates array.
• Idempotent Design: Re-running migration on v2 documents returns unchanged results with empty change logs.

Frequently Asked Questions

How does Archify determine if a workflow diagram needs migration?

Archify checks the schema version metadata within the document during the validation phase in archify/migrations/workflow-v2.mjs (lines 39-58). If the document already declares schema v2, the function returns it unchanged immediately. Only documents explicitly marked as schema v1 or lacking version metadata trigger the full migration pipeline.

What happens to explicit coordinates during the schema v1 to v2 migration?

Explicit coordinates including via points, labelAt positions, and channelX values undergo remapping via mapExplicitCoordinates in workflow-migration-geometry.mjs. The system applies a piecewise-linear horizontal rank mapper that preserves relative offsets between elements while adapting to the new rank-based layout system intrinsic to schema v2.

Is the migration process reversible or idempotent?

The migration is idempotent but not reversible. Running migrateWorkflowDocument on an already-migrated v2 document returns the exact same byte-identical document with an empty changedCoordinates array. However, the original v1 structure is not preserved in the output, making rollback impossible without maintaining separate backup files.

How does Archify handle viewBox size constraints during migration?

Archify separates authored capacity (the viewBox provided by the diagram creator) from required capacity (the space needed to display all elements). During migration, if compilation reveals that elements exceed the current viewBox, the expandableViewBox function increases dimensions monotonically—meaning it only expands to fit content, never shrinking existing viewBox boundaries even when content might fit in a smaller space.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}