What is the Archify Rendering Pipeline? A Deep Dive into the 8-Stage JSON-to-HTML Process

The Archify rendering pipeline transforms a JSON intermediate representation (IR) into a self-contained HTML diagram by chaining together CLI parsing, schema validation, type-specific renderers, geometric layout algorithms, and template injection.

The Archify rendering pipeline powers the tt-a1i/archify open-source project, converting declarative JSON diagram definitions into polished, interactive HTML visualizations. Written in Node.js, this eight-stage toolchain validates structural correctness, calculates geometric layouts, and generates standalone SVG-based diagrams without requiring external rendering dependencies.

The 8 Stages of the Archify Rendering Pipeline

The pipeline follows a strict sequence from CLI invocation to final HTML output, with each stage handled by specific modules in the repository.

1. CLI Entry Point and Command Dispatch

The process begins in archify/bin/archify.mjs, where the commandRender function (lines 54‑58) parses the command-line arguments. This entry point extracts the diagram type (e.g., architecture, lifecycle), input JSON path, and optional output destination, then dispatches to the appropriate handler.

archify render architecture examples/web-app.architecture.json output.html

2. Diagram Loading and Path Resolution

The loadDiagram function in archify/renderers/shared/cli.mjs (lines 7‑16) reads the JSON file from disk, resolves absolute paths for the output file, and prepares the diagram object for processing. This stage handles file system operations and ensures the input is readable before validation begins.

// Internal flow: loadDiagram reads file → returns diagram object + template path
import { loadDiagram } from './renderers/shared/cli.mjs';
const { diagram, templatePath, outPath } = await loadDiagram(type, inputPath, outputArg);

3. Schema Validation with AJV

Before rendering, the pipeline validates the JSON structure against pre-generated AJV schemas. The validateSchema function in archify/renderers/shared/validator.mjs (lines 30‑38) looks up the type-specific validator from generated-validators.mjs and throws descriptive errors for structural violations. This prevents malformed diagrams from reaching the layout engine.

# Human-readable validation output

archify validate lifecycle examples/agent-run.lifecycle.json

# Machine-readable JSON result

archify validate lifecycle examples/agent-run.lifecycle.json --json

4. Type-Specific Renderer Execution

Based on the diagram type, the pipeline invokes one of the render-<type>.mjs modules, such as archify/renderers/lifecycle/render-lifecycle.mjs or archify/renderers/architecture/render-architecture.mjs. These modules perform four critical substeps:

• Layout measurement: Calculating bounding boxes and component dimensions
• Validation of layout rules: Ensuring geometric constraints are satisfied
• Edge routing: Computing connection paths between elements
• SVG generation: Constructing the final <svg> string (lines 21‑27, 31‑35, 102‑117, 215‑236 in render-lifecycle.mjs)

5. Geometric Layout Helpers

Shared utilities in archify/renderers/shared/ provide mathematical primitives used by all renderers. The geometry.mjs module (lines 14‑22) exports functions like anchor, roundedPath, and labelPoint for coordinate arithmetic, while grid.mjs handles collision detection and auto-viewBox calculation. These helpers decouple geometric logic from specific diagram types.

// Example: Geometry utilities used during layout
import { anchor, roundedPath } from './renderers/shared/geometry.mjs';
const startAnchor = anchor(nodeA, 'right');
const pathData = roundedPath(startAnchor, endAnchor, radius);

6. HTML Template Injection

The writeDiagram function in archify/renderers/shared/cli.mjs (lines 19‑30) injects the generated SVG, title, subtitle, footer, and optional info-cards into archify/assets/template.html. This produces a standalone HTML file containing embedded CSS and JavaScript, requiring no external dependencies to display.

7. Optional Layout JSON Output

When invoked with the --layout-json flag (or via archify inspect), the pipeline skips HTML generation and exports the calculated layout as JSON. In render-architecture.mjs (lines 26‑34, 60‑63), the renderer calls buildLayoutReport() and outputs a JSON payload describing component boxes, connection coordinates, and viewBox dimensions—useful for CI/CD validation and testing.

# Export layout data for automated testing

archify inspect architecture

8. Post-Render Validation

The final stage runs when executing archify check. The commandCheck function in archify.mjs (lines 61‑66) invokes scripts/check-render-output.mjs to verify SVG well-formedness and ensure all animation steps are present in lifecycle diagrams, catching regressions before deployment.

Architectural Flow Visualization

The complete pipeline data flow resembles this sequence:

archify (CLI) ─► loadDiagram ─► validateSchema ─► render-<type>.mjs
          │                                 │
          │                                 ├─► layout helpers (geometry.mjs, grid.mjs)
          │                                 │
          │                                 └─► SVG string generation
          │
          └─► writeDiagram (template injection) ─► final HTML file

Practical Usage Examples

Render an Architecture Diagram

Convert a JSON definition to a standalone HTML file:

archify render architecture examples/web-app.architecture.json output.html

This executes the full pipeline: commandRender → loadDiagram → render-architecture.mjs → writeDiagram.

Validate Without Rendering

Check structural and layout correctness without generating output:

archify validate lifecycle examples/agent-run.lifecycle.json

Validation runs the schema checker and temporary rendering pipeline, reporting human-readable errors or JSON machine-readable results when using --json.

Batch Process Examples

Render all bundled example diagrams to verify the installation:

archify examples

This executes scripts/render-examples.mjs, which loops over the TARGETS array and invokes each type-specific renderer with corresponding sample JSON files.

Summary

• The Archify rendering pipeline consists of eight distinct stages: CLI parsing, diagram loading, schema validation, type-specific rendering, geometric layout calculation, HTML templating, optional JSON export, and post-render verification.
• Key entry points include archify/bin/archify.mjs for commands and archify/renderers/shared/cli.mjs for the core loading sequence.
• Type-specific renderers like render-lifecycle.mjs and render-architecture.mjs handle measurement, validation, routing, and SVG construction.
• Shared utilities in geometry.mjs and grid.mjs provide reusable geometric primitives for coordinate math and collision detection.
• The output is a self-contained HTML file generated by injecting SVG into assets/template.html, suitable for standalone deployment or CI verification via --layout-json.

Frequently Asked Questions

How does Archify validate diagram correctness before rendering?

Archify uses AJV (Another JSON Schema Validator) through archify/renderers/shared/validator.mjs. The validateSchema function loads pre-compiled validators from generated-validators.mjs specific to each diagram type (architecture, lifecycle, etc.). If validation fails, the pipeline exits with human-readable error messages indicating which JSON properties violate the schema, preventing invalid diagrams from reaching the layout engine.

Can I extract layout coordinates without generating an HTML file?

Yes. Pass the --layout-json flag to the render or validate commands, or use the archify inspect <type> shortcut. This triggers buildLayoutReport() in the type-specific renderer (e.g., lines 60‑63 in render-architecture.mjs), which outputs a JSON object containing component bounding boxes, connection paths, and viewBox dimensions to stdout instead of writing HTML.

What layout algorithms does Archify use for component placement?

The pipeline relies on grid-based layout and force-directed geometry implemented in archify/renderers/shared/grid.mjs and geometry.mjs. The render-architecture.mjs module uses grid snapping for component alignment, while render-lifecycle.mjs calculates state positions using relative spacing and validates geometry against minimum distance constraints. The anchor function in geometry.mjs ensures connection points align to node edges with configurable padding.

How can I integrate Archify into a CI/CD pipeline?

Use the validation and inspection commands for automated testing. Run archify validate <type> <file> --json to receive machine-readable pass/fail results, or archify inspect <type> to capture layout JSON for snapshot testing. The archify check command runs scripts/check-render-output.mjs to verify SVG well-formedness and animation completeness, making it suitable for pre-deployment gates in automated workflows.

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