What Are the Five Stages of the Archify Pipeline? Complete Technical Guide

The Archify pipeline processes diagram-definition JSON IR through five deterministic stages: reading the versioned JSON IR, running the typed renderer, validating HTML and SVG structure, exporting the artifact bundle, and publishing the artifact with cryptographic digests for reproducibility.

Archify transforms version-controlled diagram definitions into production-ready web artifacts through a deterministic build pipeline. Understanding the five stages of the Archify pipeline reveals how the tool ensures reproducible, validated outputs from raw JSON intermediate representations. This guide examines the actual implementation in the tt-a1i/archify repository, referencing specific source files and orchestration logic.

The Five Stages of the Archify Pipeline

Although the build logic implements four core pipeline steps, the complete workflow is logically divided into five distinct stages. These stages are orchestrated by build scripts such as scripts/build-zip.sh and visualized in the UI through scripts/gallery-template.html.

Stage 1: Read Versioned JSON IR

The pipeline begins by loading the version-controlled JSON intermediate representation (IR) that describes the diagram's nodes, edges, and metadata. This stage establishes the canonical state of the diagram definition before any rendering occurs.

According to the source code in scripts/gallery-template.html (labeled as pipeline-step 01), this step ingests the structured JSON IR that serves as the single source of truth for subsequent transformations.

Stage 2: Run the Typed Renderer

Next, the pipeline converts the JSON IR into typed model objects (TypeScript/JavaScript) and generates the corresponding SVG and HTML markup. This transformation bridges the gap between the declarative JSON structure and the imperative rendering instructions required by the browser.

As implemented in scripts/gallery-template.html (pipeline-step 02), the typed renderer validates the IR schema during conversion, ensuring that node types and edge relationships map correctly to their visual representations.

Stage 3: Check HTML and SVG Structure

Before export, the pipeline validates the generated markup to ensure well-formed SVG elements and proper HTML container hierarchy. This stage enforces Archify's layout rules, catching structural errors that could break diagram rendering in production.

The validation logic, referenced in scripts/gallery-template.html as pipeline-step 03, verifies that the rendered output adheres to the strict structural requirements defined in the Archify specification.

Stage 4: Export Artifact

The fourth stage serializes the final diagram assets—including the HTML page, SVG file, JSON source, and cryptographic digests—into a deterministic artifact bundle. This step compiles all render outputs into a cohesive package ready for distribution.

In scripts/gallery-template.html, this corresponds to pipeline-step 04, where the build system aggregates the validated markup and metadata into the final output structure.

Stage 5: Publish Artifact, Source, and Digest

The final stage writes the artifact bundle to its destination (typically a dist/ folder or zip archive) and publishes the accompanying source and cryptographic digest. This enables reproducibility verification, allowing consumers to validate that the rendered output matches the source IR exactly.

While this stage shares its origin with Stage 4 in scripts/gallery-template.html (pipeline-step 04 as the "Publish" sub-step), it operates as a distinct logical phase focused on distribution and provenance rather than compilation.

Pipeline Implementation and Key Source Files

The five stages are orchestrated through specific files in the tt-a1i/archify repository:

• scripts/gallery-template.html: Contains the HTML markup that visualizes the pipeline steps (the "pipeline-step" divs) and defines the stage boundaries.
• scripts/build-zip.sh: Shell script that drives the full pipeline sequentially, calling the renderer, validator, exporter, and publisher.
• scripts/stage-clean-skill.mjs: Implements the "stage-clean" step used by the build script to collect only tracked files before packaging.
• archify/test/workflow-compiler.test.mjs: Test suites that verify each pipeline stage works correctly and that the final artifact is reproducible.
• docs/guide.html: Provides the user-facing description of the pipeline used by the UI to render the "pipeline" component on diagram pages.

Executing the Pipeline from the Command Line

You can trigger the complete five-stage pipeline using the build script wrapper:

# Execute all five stages: read, render, validate, export, publish

node scripts/build-zip.sh \
  --src ./examples/web-app.html \
  --out ./dist/web-app.zip

Internally, the script executes the stages sequentially as illustrated in this pseudo-code:

// Internal pipeline execution flow
await readVersionedJsonIR(src);
await runTypedRenderer(ir);
await checkHtmlAndSvgStructure(rendered);
await exportArtifact(rendered);
await publishArtifactAndDigest(outPath);

Each function corresponds directly to the five stages, with the final publishArtifactAndDigest call handling both the bundle creation and the cryptographic signing that guarantees reproducibility.

Summary

• The five stages of the Archify pipeline transform JSON IR into validated, publishable web artifacts through deterministic steps.
• Stage 1 reads the versioned JSON IR from scripts/gallery-template.html (pipeline-step 01).
• Stage 2 runs the typed renderer to generate markup (pipeline-step 02).
• Stage 3 validates HTML and SVG structure against layout rules (pipeline-step 03).
• Stage 4 exports the deterministic artifact bundle (pipeline-step 04).
• Stage 5 publishes the artifact, source, and cryptographic digest for reproducibility verification (pipeline-step 04 Publish sub-step).
• Build scripts like scripts/build-zip.sh orchestrate the full sequence, while scripts/stage-clean-skill.mjs ensures only tracked files enter the bundle.

Frequently Asked Questions

Is the Archify pipeline four stages or five?

The underlying implementation defines four mechanical pipeline steps in scripts/gallery-template.html, but the complete workflow is logically separated into five stages. The fourth pipeline step (pipeline-step 04) contains two distinct logical phases: the artifact export itself and the subsequent publication with cryptographic digests. This five-stage model appears in the UI's "pipeline" view on every rendered diagram page.

What is the JSON IR in Stage 1?

The JSON IR (Intermediate Representation) is a version-controlled JSON document that declaratively describes diagram nodes, edges, and metadata. It serves as the canonical source format that Archify processes through its typed renderer. The IR format ensures that diagram definitions remain human-readable while providing the strict structure required for deterministic rendering.

How does Archify ensure reproducible builds?

Reproducibility is enforced in Stage 5 through cryptographic digests. When the pipeline publishes the artifact bundle, it generates a digest of the source JSON IR and the rendered output. Consumers can verify these digests to confirm that a rendered diagram matches its source exactly, ensuring that the dist/ folder or zip archive contains exactly what the version control system tracks.

Where are the pipeline stage tests located?

Individual stage tests reside in archify/test/, specifically in files like workflow-compiler.test.mjs. These suites verify that the typed renderer produces valid markup, that the HTML/SVG validator catches structural errors, and that the final exported artifact is deterministic across multiple build runs.

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