How to Render an Architecture Diagram Directly Using the Archify CLI

The Archify CLI converts JSON architecture definitions into standalone HTML diagrams using Node.js, validating input against schemas and outputting browser-ready files with a single command.

The tt-a1i/archify repository provides a lightweight command-line interface that lets you render an architecture diagram directly using the Archify CLI without external dependencies. Located in the renderers folder, this tool processes architecture JSON files through a synchronous pipeline that validates schemas, fetches brand assets, and generates self-contained HTML documents suitable for documentation or CI pipelines.

CLI Rendering Pipeline

The rendering process follows four distinct stages defined in archify/renderers/shared/cli.mjs and archify/renderers/architecture/render-architecture.mjs:

Loading and Validating the Diagram

The loadDiagram function (lines 19-38 in archify/renderers/shared/cli.mjs) ingests your JSON file—or defaults to examples/archify-repo.architecture.json if no input is provided. It validates the structure against archify/schemas/architecture.schema.json and prepares the HTML template for injection.

Fetching Brand Assets

If your diagram specifies brand URLs, loadDiagramWithBrandMarks (lines 44-48) asynchronously retrieves these assets before rendering begins. This is the only asynchronous operation in the pipeline; all other steps execute synchronously to ensure script reliability.

Generating SVG and Supporting Cards

The architecture-specific renderer in archify/renderers/architecture/render-architecture.mjs constructs the SVG visualization and assembles supplementary "cards" such as legends and notes. This module handles the graphical layout while delegating file operations to shared utilities.

Writing the Final HTML

Finally, writeDiagram (lines 52-70) injects the rendered SVG and metadata into assets/template.html, writing the completed file to your specified location or defaulting to architecture.html in the working directory.

Command-Line Usage

Render the Built-in Example

To see the CLI in action without custom input, execute the renderer directly. This validates your installation and generates architecture.html using the repository’s example diagram:

node archify/renderers/architecture/render-architecture.mjs

Render a Custom Architecture Diagram

Pass your own JSON file to render an architecture diagram directly using the Archify CLI with custom data. Optionally specify an output filename to override the default:

node archify/renderers/architecture/render-architecture.mjs path/to/diagram.json custom-output.html

CI/CD Pipeline Integration

Because the CLI is synchronous (excluding optional brand fetching), it integrates cleanly into automated workflows. Use it in shell scripts to generate documentation artifacts during builds:

#!/usr/bin/env bash
set -e
node archify/renderers/architecture/render-architecture.mjs "$CI_PROJECT_DIR/arch.json" "dist/architecture.html"

Input Schema and Validation Requirements

All input files must conform to the architecture schema defined in archify/schemas/architecture.schema.json. The loadDiagram function enforces this validation at runtime, rejecting malformed JSON before rendering begins. Refer to examples/archify-repo.architecture.json for a valid reference implementation.

Summary

• The Archify CLI entry point is archify/renderers/architecture/render-architecture.mjs, leveraging shared utilities in archify/renderers/shared/cli.mjs.
• Synchronous execution makes the tool safe for CI/CD scripts, with only brand-mark fetching running asynchronously.
• The pipeline validates input against architecture.schema.json, generates SVG cards, and injects them into assets/template.html.
• Default output is architecture.html, but you can specify custom paths as command-line arguments.
• All diagram types (architecture, workflow, sequence, data-flow, lifecycle) use the same CLI structure in the renderers folder.

Frequently Asked Questions

What input format does the Archify CLI require?

The CLI requires JSON files that validate against archify/schemas/architecture.schema.json. The loadDiagram function automatically validates your input and falls back to examples/archify-repo.architecture.json if no file is specified.

Can I use the Archify CLI in automated build pipelines?

Yes. According to the tt-a1i/archify source code, the CLI operates synchronously except for optional brand-mark fetching, eliminating race conditions. This design makes it ideal for bash scripts and CI environments where deterministic output is required.

How do I customize the output filename?

Provide a second command-line argument when invoking render-architecture.mjs. The writeDiagram function uses this parameter to determine the final HTML location, defaulting to architecture.html if omitted.

Does the CLI support diagram types other than architecture?

Yes. While this guide focuses on how to render an architecture diagram directly using the Archify CLI, the shared cli.mjs utilities support workflow, sequence, data-flow, and lifecycle diagrams through their respective renderer scripts in the renderers folder.

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