deep-dive

Archify Architecture Renderer Layout Features: Interactive Diagram Engine Explained

September 5, 2026 tt-a1i/archify ↗

The Archify architecture renderer provides deterministic, adaptive layout engines with interactive zooming, theme switching, and stable edge rendering, all configurable via HTML data attributes and JavaScript APIs.

The Archify architecture renderer transforms JSON-based architecture descriptions into self-contained, interactive HTML visualizations. Found in the tt-a1i/archify repository, this rendering engine emphasizes layout stability, accessibility, and responsive design. Every layout feature is implemented through specific DOM attributes and validation contracts that ensure diagrams remain readable across different viewports and themes.

Core Layout Features

Adaptive Layout Mode

The renderer supports two primary layout modes controlled by the data-reader-layout attribute on the root <html> element. When set to adaptive, the engine automatically recalculates node positions until the diagram reaches a stable size, resolving overflow before the visualization becomes visible to the user.

In generated/maka-regenerated.workflow.html (lines 10893–11009), the layout engine checks this attribute to determine whether to run the automatic positioning algorithm or respect fixed coordinates. This ensures that complex architecture diagrams scale appropriately without manual intervention.

<!DOCTYPE html>
<html data-reader-layout="adaptive">
  <head>
    <link rel="stylesheet" href="archify.css">
  </head>
  <body>
    <div id="archify-root"></div>
    <script type="module">
      import { renderArchitecture } from './renderers/architecture/render-architecture.mjs';
      const archData = {/* JSON architecture description */};
      renderArchitecture(archData, document.getElementById('archify-root'));
    </script>
  </body>
</html>

Legend Generation System

Every diagram includes a dynamically generated legend that explains colors, line styles, and symbols. The layoutLegendEntry and layoutLegendBridge functions process legend entries and attach them to the UI panel, ensuring visual consistency across different diagram types.

According to the source code in generated/maka-regenerated.workflow.html (lines 13888–13964), these functions walk through the architecture metadata to build descriptive entries that update automatically when the underlying data changes.

Responsive Theme Switching

The renderer supports dark-mode and light-mode themes via the data-theme attribute on the <html> element. Theme variables such as --bg and --text are defined in a dynamic CSS block that applies instantly without reloading the diagram.

In examples/web-app.html (lines 12536–12607), the theme system uses CSS custom properties that cascade through the SVG structure, allowing real-time color scheme adjustments.

function toggleTheme() {
  const html = document.documentElement;
  const current = html.getAttribute('data-theme') || 'light';
  html.setAttribute('data-theme', current === 'light' ? 'dark' : 'light');
}
document.getElementById('theme-btn').addEventListener('click', toggleTheme);

Zoom and Pan Controls

Users navigate diagrams through mouse wheel zooming and touch-based panning. The data-reader-scale attribute stores the current zoom factor, which the engine constrains during layout recalculation to maintain legibility across viewport sizes.

This implementation appears in generated/maka-regenerated.workflow.html (lines 11261–11341), where the scale attribute updates synchronously with the transform matrix applied to the SVG container.

Stable Edge Rendering with Data Attributes

All relationship arrows use stable identifiers via the data-edge-key attribute. This guarantees that logical connections render in identical visual positions across layout passes, which is essential for diff-stable diagrams and cross-renderer linking.

The edge stability system is defined in examples/archify-repo.html (lines 5041–5065), where each edge element carries a unique key derived from the relationship's source and target nodes.

Interactive and Export Capabilities

Interactive Node Metadata

Each rendered node carries rich metadata attributes including data-node-kind, data-node-sublabel, and data-node-context. These values are exposed through ARIA attributes for accessibility and enable interactive inspector panels that display component types and source package information.

In examples/maka-architecture.html (lines 5065–5076), nodes include semantic hooks that allow JavaScript event handlers to retrieve underlying architecture details without parsing the entire diagram structure.

Export to SVG and PNG

The renderer serializes the current SVG DOM into downloadable formats using the exportCss block containing theme variables. This ensures that exported images retain the current color scheme and styling.

The export functionality resides in examples/checkout-platform-delta.html (lines 34945–34980), where a helper function captures the computed styles along with the SVG markup.

import { exportSvgAsPng } from './export-utils.mjs';

document.getElementById('export-btn').addEventListener('click', () => {
  const svg = document.querySelector('#archify-root svg');
  exportSvgAsPng(svg, 'architecture.png');
});

Layout Validation and Constraints

Layout Contracts and Validation

Before emitting a diagram, the renderer executes a layout contract check that verifies graph invariants such as non-overlapping nodes and proper lane ordering. These contracts appear as "Stable semantic exploration hooks" in the generated HTML comments.

This validation system is documented in generated/maka-regenerated.workflow.html (lines 4062–4075), ensuring that every renderer output satisfies minimum quality standards for architecture visualization.

Manual Layout Override

For architecture views requiring precise positioning, the renderer supports a no auto-layout option set via data-node-tag="no auto-layout". This disables automatic positioning algorithms, forcing the engine to respect manually specified coordinates.

This override mechanism appears in examples/archify-repo.html (lines 5113–5117), allowing architects to maintain exact visual relationships that automatic layouts might distort.

Key Implementation Files

generated/maka-regenerated.workflow.html: Contains the complete layout engine, legend handling logic, adaptive layout algorithms, and stability contracts.
examples/maka-architecture.html: Demonstrates interactive node metadata implementation and architecture diagram patterns.
scripts/build-gallery.mjs: Assembles the renderer pipeline and injects layout-related scripts into final HTML artifacts.
integrations/deepseek-harness/lib/index.js: Exposes the renderer as a reusable module with standardized layout APIs.
examples/web-app.html: Shows integrated theme switching, zoom controls, and export functionality in a full-stack context.

Summary

Adaptive Layout Mode: Automatically scales diagrams using the data-reader-layout="adaptive" attribute to prevent overflow and ensure visibility.
Dynamic Legend System: Generates contextual legends through layoutLegendEntry and layoutLegendBridge functions based on diagram metadata.
Theme Switching: Supports instant dark/light mode transitions via CSS custom properties controlled by the data-theme attribute.
Stable Edge Identification: Uses data-edge-key attributes to maintain consistent arrow positioning across layout recalculations and diff views.
Export Functionality: Serializes styled SVG elements to PNG or SVG formats while preserving current theme variables.
Layout Contracts: Validates graph invariants before rendering to guarantee non-overlapping nodes and proper semantic structure.
Manual Override: Allows disabling automatic layout via data-node-tag="no auto-layout" for precise architectural control.

Frequently Asked Questions

How does the Archify renderer handle responsive sizing?

The renderer monitors the data-reader-layout attribute to choose between fixed and adaptive modes. In adaptive mode, the engine recalculates node positions and updates the data-reader-scale attribute until the diagram fits within the viewport constraints, as implemented in generated/maka-regenerated.workflow.html (lines 10893–11009).

Can I disable automatic layout for specific diagrams?

Yes. Set data-node-tag="no auto-layout" on the container element to bypass the automatic positioning algorithm. This forces the renderer to respect manually defined coordinates, which is useful for architecture views where precise visual relationships are critical, as shown in examples/archify-repo.html (lines 5113–5117).

What makes relationship lines stable across different renders?

The renderer assigns unique data-edge-key identifiers to every edge element based on the source and target node relationship. These stable keys ensure that logical connections appear in identical positions across different layout passes, enabling reliable diff comparisons and cross-diagram linking.

How do I export a diagram while preserving the current theme?

Use the exportSvgAsPng utility (or similar SVG serialization) to capture the current DOM state. The export process includes the exportCss block containing theme variables, ensuring that downloaded images retain the active color scheme defined by the data-theme attribute.

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"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how tt-a1i/archify works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

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