How to Use the Archify CLI to Render JSON IR to HTML

The Archify CLI transforms JSON intermediate representation files into production-ready HTML artifacts by validating input against schemas, selecting type-specific renderers, and executing them as child Node processes with configurable quality profiles.

The tt-a1i/archify repository provides a command-line interface that turns diagram definitions into validated HTML outputs. When you use the Archify CLI to render JSON IR to HTML, the tool orchestrates a pipeline that checks schemas, resolves specialized renderers, and embeds verification receipts directly into the generated artifacts.

Supported Diagram Types and Renderer Resolution

The CLI supports five distinct diagram families defined in archify/bin/archify.mjs at line 13: architecture, workflow, sequence, dataflow, and lifecycle.

When you invoke the render command, the CLI calls rendererPath() (lines 42–47) to dynamically construct the module path using the pattern archify/renderers/<type>/render-<type>.mjs. This resolution strategy ensures each diagram type uses its dedicated rendering logic while maintaining a consistent interface across the codebase.

Renderer Execution Model

The commandRender flow (lines 95–105) spawns the selected renderer as a child Node process. This isolation prevents memory leaks from diagram-specific operations and allows the CLI to capture stdout/stderr for diagnostic reporting. The parent process passes the input JSON file path and optional output destination as command arguments.

Configuration via Environment Variables

Archify propagates global settings through environment variables rather than positional arguments. When rendering, the CLI sets:

• Quality profiles: Pass --quality showcase to enable high-resolution assets. The value is injected into the renderer's environment.
• Repository root: Use --repo-root /path/to/repo to override the current working directory for source-evidence collection.

These variables ensure that renderers in archify/renderers/<type>/ receive consistent context regardless of invocation directory.

Step-by-Step: Rendering JSON to HTML

To generate HTML from your JSON IR files, execute the render subcommand with the diagram type and input file:

# Basic architecture diagram render

archify render architecture diagram.json

The CLI validates the JSON against Archify's schema definitions before execution. If validation passes, the tool invokes the appropriate renderer module and writes the output.

Specifying Output Paths and Quality

Control the destination and visual fidelity using optional flags:

# Explicit output path

archify render workflow workflow.json out.html

# High-resolution showcase quality

archify render dataflow dataflow.json --quality showcase

# Alternative repository root

archify render lifecycle lifecycle.json --repo-root /path/to/repo

The archify/renderers/shared/output-path.mjs module handles safe path resolution to prevent accidental overwrites of existing artifacts.

Output Artifacts and Verification

Every successful render produces an HTML file containing an embedded source-evidence receipt. This cryptographic footprint enables downstream verification and delta-compare operations against the original JSON IR. The base template located at archify/assets/template.html provides the container into which the rendered SVG and metadata are injected.

Key Implementation Files

Understanding the source structure helps debug rendering issues:

• archify/bin/archify.mjs: Main entry point that parses arguments, selects renderers via rendererPath(), and orchestrates the pipeline.
• archify/renderers/architecture/render-architecture.mjs: Renderer implementation for system architecture diagrams.
• archify/renderers/workflow/render-workflow.mjs: Handles workflow visualization rendering.
• archify/renderers/sequence/render-sequence.mjs: Processes sequence diagram IR.
• archify/renderers/dataflow/render-dataflow.mjs: Renders dataflow diagrams.
• archify/renderers/lifecycle/render-lifecycle.mjs: Manages lifecycle state visualizations.
• archify/renderers/shared/output-path.mjs: Utility for safe output path resolution.
• archify/assets/template.html: Base HTML template for all rendered outputs.

Summary

• The Archify CLI supports five diagram types: architecture, workflow, sequence, dataflow, and lifecycle.
• Renderer selection uses the rendererPath() function in archify/bin/archify.mjs to resolve type-specific modules.
• Execution occurs via child Node processes spawned by the commandRender flow, with options passed through environment variables.
• Use --quality for asset resolution profiles and --repo-root to change the source evidence base directory.
• Output HTML includes embedded verification receipts derived from archify/assets/template.html.

Frequently Asked Questions

What diagram types does Archify support?

Archify supports five diagram families defined in the TYPES constant at line 13 of archify/bin/archify.mjs: architecture, workflow, sequence, dataflow, and lifecycle. Each type has a dedicated renderer module located under archify/renderers/<type>/.

How does the CLI select which renderer to use?

The CLI uses the rendererPath() function (lines 42–47) to construct a dynamic import path matching the pattern archify/renderers/<type>/render-<type>.mjs. This function maps the command-line type argument to the corresponding Node module.

Can I specify custom output directories when rendering?

Yes. Pass the desired output path as the third positional argument: archify render <type> input.json output.html. The archify/renderers/shared/output-path.mjs module validates the path to prevent overwrites.

What is the purpose of the source-evidence receipt in the HTML output?

The embedded receipt enables downstream verification and delta-compare operations by cryptographically linking the rendered HTML back to the original JSON IR and repository state. This feature supports audit trails and artifact validation in CI/CD pipelines.

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