How Archify Generates Architecture Diagrams from AI Code Agent Output

Archify converts structured JSON output from AI code agents into rendered architecture diagrams using a deterministic client-side pipeline that extracts the data, transforms it into Mermaid syntax, and renders it as SVG without server-side processing.

The tt-a1i/archify repository implements a lightweight static-site approach to visualizing software designs produced by AI coding agents. By standardizing on a simple JSON schema for component descriptions and relationships, Archify eliminates the need for complex diagramming backends while keeping diagrams synchronized with agent-generated documentation.

The Archify Pipeline Architecture

Archify processes AI-generated architecture descriptions through a deterministic five-stage pipeline that runs entirely in the browser. This design ensures that architecture diagrams remain portable and always reflect the latest agent output without requiring server-side rendering infrastructure.

JSON Schema Extraction

The pipeline begins when an AI code agent emits a structured design description wrapped in a fenced JSON code block within Markdown content. According to the tt-a1i/archify source code, the system expects a predefined schema containing components, relationships, and optional metadata fields.

In examples/maka-architecture.architecture.json, the repository demonstrates the expected format:

{
  "components": [
    { "id": "frontend", "type": "ReactApp", "label": "Frontend" },
    { "id": "api", "type": "NodeService", "label": "API Service" },
    { "id": "db", "type": "Postgres", "label": "Database" }
  ],
  "relationships": [
    { "from": "frontend", "to": "api", "label": "HTTP" },
    { "from": "api", "to": "db", "label": "SQL" }
  ]
}

The Archify loader scans the DOM for the first <pre><code class="language-json"> block, validates the parsed object against the expected schema, and prepares it for transformation.

Mermaid Syntax Generation

Once extracted, the JSON object undergoes transformation into Mermaid flowchart syntax. The conversion logic maps each component to a node identifier and each relationship to a directed edge with optional labels.

The transformation follows this mapping:

• Components become Mermaid nodes using the syntax id[Label]
• Relationships become directed edges using the syntax from -->|label| to

This transformation occurs client-side within the browser environment defined in scripts/start-template.html, which serves as the base HTML template containing the Archify initialization logic.

Rendering Architecture Diagrams in the Browser

After generating the Mermaid source string, Archify injects the content into a container div with the class mermaid and invokes the Mermaid runtime to produce the final SVG visualization.

The rendering process leverages the Mermaid JavaScript library loaded via CDN, as implemented in the starter template:

<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>
  function renderArchifyDiagram() {
    const codeBlock = document.querySelector('pre > code.language-json');
    const data = JSON.parse(codeBlock.textContent);
    
    const mermaidSrc = data.components.map(c => `${c.id}[${c.label}]`).join('\n') +
      '\n' + data.relationships.map(r => `${r.from} -->|${r.label}| ${r.to}`).join('\n');
    
    const container = document.createElement('div');
    container.className = 'mermaid';
    container.textContent = mermaidSrc;
    
    codeBlock.parentElement.parentElement.replaceWith(container);
    mermaid.run();
  }
  renderArchifyDiagram();
</script>

This approach replaces the original JSON code block with the rendered diagram, maintaining the document flow while providing visual representation of the architecture.

Key Implementation Files

The tt-a1i/archify repository contains several critical files that demonstrate the end-to-end workflow:

• examples/maka-architecture.html – Demonstrates a complete implementation showing how AI-generated JSON output transforms into a visual diagram using Archify's client-side logic.

• examples/maka-architecture.architecture.json – Contains the sample JSON structure that AI agents should produce, serving as the canonical reference for the input schema.

• scripts/start-template.html – Provides the base HTML template that loads the Mermaid library and contains the Archify loader script responsible for extraction and rendering.

• archify/test/gallery.test.mjs – Contains the test suite that validates the end-to-end conversion pipeline from JSON extraction to rendered diagram output.

Summary

• Archify uses a client-side pipeline to convert AI agent JSON output into architecture diagrams without server processing.
• The system expects a standardized JSON schema with components and relationships arrays, as demonstrated in examples/maka-architecture.architecture.json.
• Mermaid syntax generation transforms the structured data into flowchart definitions that the Mermaid runtime renders as SVG.
• The implementation resides in lightweight HTML templates and JavaScript loaders found in scripts/start-template.html.
• The archify/test/gallery.test.mjs test suite validates the complete transformation pipeline from agent output to visual diagram.

Frequently Asked Questions

What JSON schema does Archify require for architecture diagrams?

Archify expects a JSON object containing two primary arrays: components (with id, type, and label fields) and relationships (with from, to, and label fields). The examples/maka-architecture.architecture.json file in the tt-a1i/archify repository provides the canonical reference implementation that AI agents should emulate when generating output.

Does Archify require server-side rendering infrastructure?

No. The entire diagram generation pipeline runs client-side in the browser. The Archify loader script extracts the JSON from the DOM, transforms it into Mermaid syntax, and invokes the Mermaid JavaScript library to render SVG diagrams directly in the user's browser, eliminating the need for backend processing or external API calls.

How does Archify handle styling and theming of generated diagrams?

Archify delegates visual styling to the Mermaid runtime, which supports light and dark themes through CSS variables and configuration options. The base template in scripts/start-template.html loads the Mermaid library with default styling, and developers can extend this by adding custom CSS or Mermaid theme configurations to match their documentation site's visual requirements.

Can Archify export diagrams as static images?

While the core implementation focuses on live SVG rendering via Mermaid, the browser-based approach allows for straightforward export to PNG or other formats using standard browser APIs or Mermaid's built-in export functionality. The SVG output can be serialized to a data URI for embedding in documents or converted to raster formats using canvas-based techniques.

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