# How to Convert Mermaid Diagrams to Archify JSON: A Complete Guide

> Learn to convert Mermaid diagrams to Archify JSON. Map nodes, edges, and groups to Archify's schema, then validate and render using the CLI for seamless integration.

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

---

**Archify does not provide a built-in Mermaid-to-JSON converter, but you can transform any Mermaid diagram into Archify's typed JSON format by mapping nodes, edges, and groups to Archify's schema fields, then validating and rendering through the CLI.**

The `tt-a1i/archify` repository defines a strict JSON intermediate representation (IR) for architecture diagrams, workflows, sequences, and more. Converting from Mermaid requires understanding this schema and performing a manual but straightforward structural mapping. This guide walks you through the complete conversion process using actual source files from the repository.

## Understanding Archify's JSON Schema

Before converting, you need to familiarize yourself with Archify's type system. The schema files define valid structure for each diagram type.

- **Schema location**: `archify/schemas/` contains formal JSON schemas for all diagram types.
- **Documentation**: [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) provides the complete schema reference.
- **Architecture schema**: [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) governs infrastructure and system diagrams—the most common target for Mermaid flowchart conversions.

Archify's JSON structure differs from Mermaid's declarative syntax. Instead of inline arrow definitions, Archify separates **nodes** (entities), **relations** (connections), and **groups** (visual clusters) into distinct arrays with typed metadata.

## Mapping Mermaid Elements to Archify Fields

The conversion follows a predictable pattern across element types.

### Nodes to `nodes[]`

| Mermaid Syntax | Archify Field | Purpose |
|---------------|-------------|---------|
| `A[Browser]` | `id: "A"`, `label: "Browser"` | Unique identifier and display text |
| Implicit type | `type: "client"` / `"service"` / `"store"` | Archify requires explicit node typing |

### Edges to `relations[]`

| Mermaid Syntax | Archify Field | Purpose |
|---------------|-------------|---------|
| `A --> B` | `source: "A"`, `target: "B"` | Directed connection endpoints |
| `A --"text"--> B` | `label: "text"` | Optional edge annotation |

### Sub-graphs to `groups[]`

Mermaid's `subgraph` blocks map to Archify's `groups[]` array, which handles visual clustering without affecting connection logic.

### Styling Considerations

Mermaid's CSS-based theming does not transfer directly. Archify applies visuals through:
- `meta.visual_preset` — predefined layout styles (e.g., `"signal-flow"`, `"layered"`)
- `meta.animation` — animation behavior (`"none"`, `"semantic"`, `"stepped"`)

## Complete Conversion Example

Below is a Mermaid flowchart and its equivalent Archify JSON, validated against [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json).

**Mermaid source:**

```mermaid
flowchart TD
    A[Browser] --> B[Web App]
    B --> C[API Server]
    C --> D[Postgres DB]

```

**Archify JSON output:**

```json
{
  "meta": {
    "type": "architecture",
    "visual_preset": "signal-flow",
    "animation": "none"
  },
  "nodes": [
    { "id": "A", "label": "Browser", "type": "client" },
    { "id": "B", "label": "Web App", "type": "service" },
    { "id": "C", "label": "API Server", "type": "service" },
    { "id": "D", "label": "Postgres DB", "type": "store" }
  ],
  "relations": [
    { "source": "A", "target": "B", "label": "" },
    { "source": "B", "target": "C", "label": "" },
    { "source": "C", "target": "D", "label": "" }
  ]
}

```

Key decisions in this mapping:
- Node types assigned based on architectural role (`client` for browser, `service` for application layers, `store` for database)
- Empty labels preserved where Mermaid had no edge text
- `signal-flow` preset selected for left-to-right data flow visualization

## Validating and Rendering Your JSON

After creating your JSON file, use the CLI entry point at `archify/bin/archify.mjs` to process it.

### Step 1: Validation

Run the `validate` command with your diagram type and quality tier:

```bash
node archify/bin/archify.mjs validate architecture login-flow.architecture.json --quality showcase --json

```

A clean receipt confirms compliance with [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). Validation catches structural errors before rendering.

### Step 2: Rendering

Generate a shareable HTML artifact:

```bash
node archify/bin/archify.mjs render architecture login-flow.architecture.json login-flow.html --open

```

The resulting [`login-flow.html`](https://github.com/tt-a1i/archify/blob/main/login-flow.html) is self-contained—no server required. The `--open` flag launches it in your default browser immediately.

## Scaling Conversions for Large Diagrams

For diagrams with dozens of nodes, manual JSON editing becomes impractical. Consider these workflows:

- **Spreadsheet intermediate**: Copy Mermaid node/edge definitions into columns (`id`, `label`, `type`, `source`, `target`), add Archify type values, then export to JSON using your tool of choice (Python `json` module, Node.js script, or Excel/Sheets add-on)

- **Natural language prototyping**: The CLI's `guide` command generates starter JSON from descriptions:

```bash
node archify/bin/archify.mjs guide "three-tier web application with load balancer, two app servers, and primary-replica database"

```

Adjust the generated structure to match your original Mermaid diagram's topology.

## Key Source Files for Reference

| File | Purpose |
|------|---------|
| [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) | Schema overview and diagram type documentation |
| [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Formal validation rules for architecture diagrams |
| [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json) | Production-ready example matching common Mermaid patterns |
| `archify/bin/archify.mjs` | CLI entry point for all conversion commands |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Complete contract including delivery and validation requirements |

## Summary

- **Archify has no automatic Mermaid converter**—conversion requires manual schema mapping.
- **Core mapping**: Mermaid nodes → `nodes[]` with explicit `type`, edges → `relations[]`, sub-graphs → `groups[]`.
- **Validation is mandatory**—use `archify/bin/archify.mjs validate` to check against `archify/schemas/[type].schema.json`.
- **Output is portable**—the `render` command produces standalone HTML files.
- **Scale with tooling**—spreadsheets or the `guide` command accelerate large diagram conversions.

## Frequently Asked Questions

### Can I convert Mermaid diagrams automatically without manual mapping?

No. As of the current `tt-a1i/archify` codebase, no built-in parser translates Mermaid syntax directly to Archify JSON. The structural differences—particularly Archify's requirement for explicit node types and separated metadata fields—necessitate manual transformation or custom scripting.

### What happens if my JSON fails validation?

The `validate` command outputs a detailed receipt indicating schema violations. Common issues include missing required `type` fields on nodes, malformed relation references to non-existent node IDs, or incorrect `meta.type` values. Fix these in your JSON and re-run validation before attempting to render.

### Which Mermaid diagram types map best to Archify?

Flowcharts and graph declarations (`flowchart TD`, `graph LR`) translate most naturally to Archify's `architecture` type. Sequence diagrams can map to Archify's `sequence` type using similar node/edge logic, though timing and activation boxes require additional `meta` configuration. State diagrams and Gantt charts have less direct equivalents in the current schema set.

### Are Archify's visual presets compatible with Mermaid themes?

No direct compatibility exists. Mermaid's CSS-based theming (colors, fonts, line styles) does not transfer to Archify. You must select from Archify's predefined `visual_preset` values and adjust `meta.animation` independently. The rendered output will use Archify's consistent design system rather than replicating Mermaid's appearance.