internals

How the Archify Workflow Renderer Works: A Zero-Dependency Rendering Pipeline Explained

September 5, 2026 tt-a1i/archify ↗

The Archify workflow renderer is a typed, zero-dependency pipeline that transforms Workflow JSON IR into interactive HTML/SVG diagrams through parsing, typed rendering, and layout-check hooks.

The Archify workflow renderer powers the tt-a1i/archify repository's ability to visualize complex workflows without requiring external libraries. This article breaks down exactly how the renderer processes workflow definitions and generates browser-native diagrams that support focus states, tooltips, and dynamic theming.

Parsing and Validation Stage

The renderer begins by loading and validating the input against archify/schemas/workflow.schema.json. This schema defines the Workflow JSON IR structure that all rendered workflows must follow.

During this stage, the renderer assigns stable IDs to each node. These deterministic identifiers (e.g., node-renderers) ensure that the same workflow produces identical DOM structures across multiple renders. This stability is critical for downstream verification and UI state persistence.

The schema loading and ID assignment logic resides in generated/maka-regenerated.workflow.html, which contains the complete bundled renderer implementation.

Typed Rendering Architecture

Archify ships five typed renderers: architecture, workflow, sequence, dataflow, and lifecycle. The workflow renderer is one of these specialized implementations.

Each typed renderer walks the validated graph and emits SVG elements including <g>, <path>, and <text> nodes. The workflow renderer specifically enriches these elements with data attributes that drive interactivity:

  • data-node-id — stable identifier for selection tracking
  • data-node-kind — node classification for styling
  • data-node-context — semantic context for verification hooks
  • data-node-label — display text for tooltips and accessibility

These attributes are embedded directly in generated/maka-regenerated.workflow.html and enable the renderer's focus, tooltip, and theme-switching capabilities without external dependencies.

Layout Checks and Semantic Hooks

After node creation, the renderer executes layout-check hooks (marked by comments reading /* Stable semantic exploration hooks emitted by every renderer. */ in the source). These hooks perform three critical operations:

  1. Edge geometry computation — calculates path data using d="M … L …" syntax for SVG <path> elements
  2. Style application — assigns classes like a-emphasis and a-dashed based on edge semantics
  3. Hook embedding — inserts semantic markers that verification tools use to prove the rendered graph matches repository evidence

The edge calculation logic sets stroke widths, attaches arrowhead markers, and ensures proper layering of visual elements. All of this occurs within the single generated HTML file that ships with the repository.

Interactivity and Accessibility Features

The renderer produces accessible, keyboard-navigable diagrams by injecting standard ARIA attributes and event handlers. Every interactive element receives:

  • tabindex for keyboard focus
  • role attributes for screen reader context
  • aria-label for descriptive text
  • Click handlers for selection state management

These features are implemented directly in the rendered output at examples/workflow-agent-tool-call-rendered.html, demonstrating the renderer's production-ready accessibility.

Theme Support Through CSS Variables

The workflow renderer supports dynamic theming without JavaScript framework dependencies. Colors derive from CSS custom properties defined in scripts/start-template.html:

:root {
  --bg: #ffffff;
  --text: #1a1a1a;
  /* additional theme variables */
}

Theme switching occurs by toggling the data-theme attribute on the <html> element, which propagates to all rendered diagrams through CSS inheritance.

Using the Workflow Renderer

The following example shows how to invoke the renderer in a web page:

<!-- Load the Archify renderer (built-in, no external deps) -->
<script type="module">
  import { renderWorkflow } from 'https://cdn.jsdelivr.net/gh/tt-a1i/archify@main/archify/renderer.js';

  // Example workflow JSON – follows the schema in archify/schemas/workflow.schema.json
  const workflow = {
    "$schema": "https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json",
    "id": "example-workflow",
    "steps": [
      { "id": "fetch",   "type": "fetch",   "next": "process" },
      { "id": "process", "type": "transform","next": "store"   },
      { "id": "store",   "type": "save",    "next": null }
    ]
  };

  // Render into the container <div id="graph"></div>
  const container = document.getElementById('graph');
  renderWorkflow(container, workflow);
</script>

<div id="graph"></div>

This code produces SVG output matching the structure found in examples/workflow-agent-tool-call-rendered.html.

Key Implementation Files

File Purpose
archify/schemas/workflow.schema.json JSON Schema defining the workflow IR shape
generated/maka-regenerated.workflow.html Bundled renderer with all SVG generation logic
examples/workflow-agent-tool-call.html Raw workflow IR example
examples/workflow-agent-tool-call-rendered.html Rendered output showing final diagram
scripts/start-template.html Theme CSS and renderer loading boilerplate

Summary

  • The Archify workflow renderer processes Workflow JSON IR through a three-stage pipeline: parsing/validation, typed rendering, and layout checks
  • Implementation lives entirely in generated/maka-regenerated.workflow.html with zero external dependencies
  • Stable IDs ensure deterministic output for verification and state management
  • Data attributes (data-node-id, data-node-kind, etc.) power interactivity without framework overhead
  • CSS variables enable dynamic theming through the data-theme attribute
  • The renderer produces accessible SVG with proper ARIA attributes and keyboard navigation

Frequently Asked Questions

What is Workflow JSON IR in Archify?

Workflow JSON IR (Intermediate Representation) is a JSON format defined by archify/schemas/workflow.schema.json that describes workflow structure, steps, and connections. It serves as the declarative input that the workflow renderer transforms into visual diagrams. The IR separates content from presentation, allowing the same workflow definition to render consistently across different contexts.

Does the Archify workflow renderer require any external libraries?

No. The Archify workflow renderer is zero-dependency. All logic—including parsing, SVG generation, layout calculation, and interactivity—ships in a single generated HTML file. The renderer uses only browser-native APIs: the DOM for element creation, CSS for styling, and JavaScript modules for code organization.

How does the renderer handle accessibility?

The workflow renderer injects ARIA attributes and keyboard navigation support directly into generated SVG elements. Each interactive node receives tabindex, role, and aria-label attributes. This approach ensures screen reader compatibility and keyboard operability without requiring external accessibility libraries or frameworks.

Can I customize the visual appearance of rendered workflows?

Yes. The renderer uses CSS custom properties (variables like --bg, --text) defined in scripts/start-template.html. You can override these variables or modify the data-theme attribute on the <html> element to switch between light, dark, or custom themes. The SVG structure also accepts standard CSS for stroke colors, dash patterns, and typography.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →