# How Archify Generates Architecture Diagrams from AI Code Agent Output

> Discover how Archify generates architecture diagrams from AI code agent output. It transforms JSON into Mermaid syntax and renders SVGs client-side for efficient visualization.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-04

---

**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`](https://github.com/tt-a1i/archify/blob/main/examples/maka-architecture.architecture.json), the repository demonstrates the expected format:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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:

```html
<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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.