How to Render an Archify Diagram with Validation: Complete Guide

Use the Archify CLI with npx archify render or call renderWorkflow() programmatically to validate your diagram against the workflow schema before generating HTML/SVG output.

Archify is a declarative, schema-driven tool for authoring, visualising, and validating software-architecture diagrams. When you render an Archify diagram, validation happens automatically before any visual output is produced, ensuring structural integrity and preventing wasted rendering cycles on malformed definitions.

How Archify's Validation-First Rendering Works

The rendering pipeline in archify/renderers/workflow enforces a strict five-step process:

1. Load the diagram definition — the JSON or YAML file is read and parsed.
2. Schema validation — Archify validates against archify/schemas/workflow.schema.json, checking required fields, data types, and relational constraints (unique node IDs, permissible edge directions). Failures throw SchemaValidationError with detailed path-based messages.
3. Create the internal model — validated definitions become a graph model for the layout engine.
4. Layout and render — the model generates responsive HTML/SVG output embeddable in documentation.
5. Optional post-render checks — semantic contracts in archify/references/authoring-contract.md verify "no orphan nodes" and layer ordering constraints.

Because validation precedes all rendering work, you receive immediate feedback without resource waste. The CLI exits non-zero on failure, making CI integration straightforward.

Render an Archify Diagram Using the CLI

The simplest way to render an Archify diagram with validation is through the command-line interface.

# Render a diagram and automatically validate it

npx archify render path/to/diagram.architecture.json \
  --output dist/diagram.html

Validation errors halt execution with descriptive messages:

✖ Validation error: "nodes[3].id" is missing required property "id"

The CLI implementation resides in scripts/run-tests.mjs, with the rendering entry point documented in archify/renderers/workflow/README.md.

Validate Without Rendering

Use --dry-run for pure validation without output generation:

npx archify render diagram.architecture.json --dry-run

This flag enables fast pre-commit or CI validation checks.

Render an Archify Diagram Programmatically in Node.js

For custom integrations, import renderWorkflow from archify/renderers/workflow:

import { renderWorkflow } from 'archify/renderers/workflow';
import { readFile } from 'fs/promises';

async function renderDiagram(filePath) {
  const raw = await readFile(filePath, 'utf8');
  const diagram = JSON.parse(raw);

  // Validates against workflow schema before rendering
  const html = await renderWorkflow(diagram, { output: 'string' });

  console.log('Rendered diagram HTML:', html);
}

renderDiagram('examples/maka-architecture.architecture.json')
  .catch(err => {
    console.error('Rendering failed:', err.message);
    // SchemaValidationError contains detailed path info
  });

The renderWorkflow function signature accepts:

• First argument: the parsed diagram object
• Second argument: options including output: 'string' or output: 'file'

Integrate Archify Validation into CI/CD Pipelines

Archify's non-zero exit codes and --dry-run flag enable seamless CI integration:

# .github/workflows/archify.yml

name: Validate & Render Archify Diagrams
on: [push, pull_request]

jobs:
  archify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Archify
        run: npm ci
      - name: Validate all diagrams
        run: |
          for f in $(git ls-files '**/*.architecture.json'); do
            npx archify render "$f" --dry-run || exit 1
          done
      - name: Render production diagrams
        run: |
          npx archify render docs/architecture.architecture.json \
            --output public/diagram.html

This workflow fails fast on schema violations before attempting production renders.

Key Schema and Validation Files

File	Purpose
archify/renderers/workflow/README.md	Core rendering API and validation flow
archify/schemas/workflow.schema.json	JSON-Schema defining diagram structure
archify/references/authoring-contract.md	Semantic post-render constraints
scripts/run-tests.mjs	CLI entry point wiring validation to rendering
examples/maka-architecture.architecture.json	Reference diagram for testing

Summary

• Validation is automatic: every render path validates against archify/schemas/workflow.schema.json first.
• CLI or programmatic: use npx archify render or renderWorkflow() from archify/renderers/workflow.
• Fast feedback: --dry-run enables validation-only CI checks without file generation.
• Detailed errors: SchemaValidationError provides path-specific messages for rapid debugging.

Frequently Asked Questions

What happens if my Archify diagram fails validation?

Rendering aborts immediately with a SchemaValidationError containing the exact JSON path and description of each violation. The CLI prints these details and exits with a non-zero status code.

Can I skip validation when rendering an Archify diagram?

No. The rendering pipeline in archify/renderers/workflow enforces validation as a mandatory first step. This design prevents the generation of misleading or broken visualizations from malformed input.

How do I validate multiple Archify diagrams at once?

Use shell iteration with --dry-run as shown in the CI example above. The render command accepts single files; batch operations require scripting or CI workflow loops.

What is the difference between schema validation and semantic checks?

Schema validation (in archify/schemas/workflow.schema.json) verifies structural correctness—required fields, types, unique IDs. Semantic checks (defined in archify/references/authoring-contract.md) run optionally after rendering to enforce architectural rules like "no orphan nodes" or correct layer ordering.

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