How to Render a Diagram from JSON IR using the Archify CLI

The Archify CLI converts typed JSON Intermediate Representation (IR) files into self-contained HTML diagrams by executing archify render <type> <input.json> to invoke type-specific renderers that output interactive SVG visualizations complete with validation receipts.

The Archify toolset transforms structured JSON IR into publication-ready architecture diagrams without manual drawing tools. This guide demonstrates the exact commands, source file paths, and validation steps required to render diagrams from JSON IR using the Archify CLI in the tt-a1i/archify repository.

CLI Architecture and Entry Points

The command-line interface entry point lives in archify/bin/archify.mjs. This module parses arguments and dispatches sub-commands between lines 13-27, validating the diagram type before spawning the appropriate renderer.

Each diagram category has a dedicated renderer module located at archify/renderers/<type>/render-<type>.mjs. For example, architecture diagrams are processed by archify/renderers/architecture/render-architecture.mjs. These modules read the JSON IR, compute layouts, and emit the final HTML artifact containing embedded SVG.

Supported Diagram Types

Archify supports five distinct diagram categories. Each type enforces a specific JSON schema located in archify/schemas/<type>.schema.json:

• architecture – System component diagrams showing nodes and relationships
• workflow – Process flow and decision graphs
• sequence – Temporal interaction diagrams
• dataflow – Data transformation pipelines
• lifecycle – State transition and stage progression diagrams

Command Syntax and Options

The render sub-command follows this signature:

archify render <type> <input.json> [output.html] [--quality standard|showcase] [--repo-root <path>]

• <type> – Required diagram category (e.g., architecture)
• <input.json> – Path to the typed JSON IR file conforming to the schema
• [output.html] – Optional destination file; defaults to <type>.html in the working directory
• --quality – Rendering preset: standard for fast output or showcase for polished SVG with motion effects
• --repo-root – Required only for architecture diagrams that embed source-evidence links

Step-by-Step Rendering Workflow

1. Prepare the JSON IR File

Create a JSON file that validates against the target type's schema. For architecture diagrams, the file must match archify/schemas/architecture.schema.json. The structure requires a meta object, a nodes array, and a relationships array:

{
  "meta": { "visual_preset": "signal-flow" },
  "nodes": [
    { "id": "browser", "label": "Browser" },
    { "id": "api", "label": "API Server" },
    { "id": "redis", "label": "Redis Cache" },
    { "id": "postgres", "label": "PostgreSQL" }
  ],
  "relationships": [
    { "source": "browser", "target": "api", "label": "HTTP" },
    { "source": "api", "target": "redis", "label": "GET/SET" },
    { "source": "api", "target": "postgres", "label": "SQL" }
  ]
}

2. Execute the Render Command

Run the CLI from your terminal. The following example renders an architecture diagram with standard quality:

archify render architecture web-app.architecture.json web-app.html

For higher-fidelity output suitable for presentations, append the showcase quality flag:

archify render architecture web-app.architecture.json web-app-showcase.html --quality showcase

The command validates the JSON against the schema, sets the ARCHIFY_QUALITY_PROFILE environment variable for the renderer, and invokes archify/renderers/architecture/render-architecture.mjs to process the file.

3. Understand the Output Artifacts

The CLI writes a self-contained HTML file to the specified destination. Opening this file in a browser reveals:

• The rendered SVG diagram with calculated layouts
• Interactive focus controls for navigating complex graphs
• An export menu for downloading vector graphics
• Embedded validation receipts confirming schema compliance

Quality Profiles and Rendering Options

The --quality parameter controls the rendering pipeline's fidelity. When set to showcase, the renderer applies additional SVG polishing and motion effects. This setting passes through the ARCHIFY_QUALITY_PROFILE environment variable to the underlying renderer modules, allowing type-specific optimizations for anti-aliasing, animation curves, and layout density.

Summary

• Entry point: The CLI logic resides in archify/bin/archify.mjs (lines 13-27)
• Type validation: JSON IR must conform to schemas in archify/schemas/<type>.schema.json
• Renderer location: Each type has a specific renderer at archify/renderers/<type>/render-<type>.mjs
• Command structure: archify render <type> <input.json> with optional output path and quality flags
• Output: Single self-contained HTML file with embedded SVG, validation metadata, and interactive controls

Frequently Asked Questions

What JSON schema validates architecture diagrams?

Architecture diagrams are validated against archify/schemas/architecture.schema.json before rendering begins. This schema defines the required meta, nodes, and relationships structures.

How do I generate a showcase-quality diagram?

Append the --quality showcase flag to your render command. This sets the ARCHIFY_QUALITY_PROFILE environment variable and instructs the renderer to apply enhanced SVG polishing and motion effects suitable for presentations.

Where does the sequence diagram renderer logic live?

The sequence diagram implementation resides at archify/renderers/sequence/render-sequence.mjs. This module parses the JSON IR, calculates temporal layouts, and emits the final HTML artifact.

Can I specify a custom output filename?

Yes. Provide the desired filename as the third positional argument after the input JSON. If omitted, the CLI defaults to <type>.html (e.g., architecture.html) in the current working directory.

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