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

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 provides the complete schema reference.
• Architecture schema: 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.

Mermaid source:

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

Archify JSON output:

{
  "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:

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. Validation catches structural errors before rendering.

Step 2: Rendering

Generate a shareable HTML artifact:

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

The resulting 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:

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	Schema overview and diagram type documentation
archify/schemas/architecture.schema.json	Formal validation rules for architecture diagrams
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	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.

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