How to Convert Mermaid Diagrams (Flowchart, Sequence, State) to Archify JSON: A Complete Guide

Use the Archify CLI convert command to transform any Mermaid diagram file into a structured JSON intermediate representation (IR) that follows the Archify Architecture schema.

Archify—-the information-architecture engine in the tt-a1i/archify repository—-can ingest Mermaid source files and emit a machine-readable JSON format used by renderers, validators, editors, and CI pipelines. This conversion bridges visual diagramming with programmatic architecture management.

Prerequisites

• Node.js installed (the CLI runs via npx)
• A Mermaid diagram file (.mmd) containing a flowchart, sequence diagram, or state diagram

The Archify Convert Command

The entry point for conversion is implemented in scripts/cli.mjs (compiled to archify.mjs). It exposes a convert sub-command with this interface:

npx archify convert \
  --input path/to/diagram.mmd \
  --output path/to/diagram.architecture.json

Required Parameters

Flag	Description
--input	Path to a Mermaid source file (.mmd)
--output	Destination path for the Archify JSON IR (.architecture.json)

How the Conversion Works

Under the hood, the conversion pipeline follows three stages as implemented in archify/src/mermaid-to-json.js:

1. Parse — The mermaid npm package generates an AST from the source
2. Map — Archify walks the AST and translates elements to domain concepts:
   • Flowcharts → components + connections + layout hints
   • Sequence diagrams → components (participants) + messages
   • State diagrams → states + transitions
3. Serialize — Output conforms to archify/schemas/architecture.schema.json

The resulting structure matches real-world fixtures like examples/web-app.architecture.json and examples/archify-repo.architecture.json.

Conversion Examples by Diagram Type

Flowchart to Archify JSON

Save this as flowchart.mmd:

flowchart TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Action 1]
  B -->|No| D[Action 2]
  C --> E[End]
  D --> E

Run the conversion:

npx archify convert \
  --input flowchart.mmd \
  --output flowchart.architecture.json

Generated flowchart.architecture.json:

{
  "type": "architecture",
  "components": [
    {"id":"A","label":"Start"},
    {"id":"B","label":"Decision"},
    {"id":"C","label":"Action 1"},
    {"id":"D","label":"Action 2"},
    {"id":"E","label":"End"}
  ],
  "connections": [
    {"from":"A","to":"B"},
    {"from":"B","to":"C","label":"Yes"},
    {"from":"B","to":"D","label":"No"},
    {"from":"C","to":"E"},
    {"from":"D","to":"E"}
  ],
  "layout": {"engine":"mermaid","direction":"TD"}
}

Sequence Diagram to Archify JSON

Save this as conversation.mmd:

sequenceDiagram
  participant Alice
  participant Bob
  Alice->>Bob: Hello Bob, how are you?
  Bob-->>Alice: I am good thanks!

Run the conversion:

npx archify convert \
  --input conversation.mmd \
  --output conversation.architecture.json

Generated conversation.architecture.json:

{
  "type":"architecture",
  "components":[
    {"id":"Alice","role":"participant"},
    {"id":"Bob","role":"participant"}
  ],
  "messages":[
    {"from":"Alice","to":"Bob","text":"Hello Bob, how are you?"},
    {"from":"Bob","to":"Alice","text":"I am good thanks!"}
  ],
  "layout":{"engine":"mermaid","direction":"LR"}
}

Note the structural difference: sequence diagrams use messages instead of connections, and components carry a role field.

State Diagram to Archify JSON

Save this as states.mmd:

stateDiagram-v2
  [*] --> Still
  Still --> [*]
  Still --> Moving
  Moving --> Still

Run the conversion:

npx archify convert \
  --input states.mmd \
  --output states.architecture.json

Generated states.architecture.json:

{
  "type":"architecture",
  "states":[
    {"id":"[*]"},
    {"id":"Still"},
    {"id":"Moving"}
  ],
  "transitions":[
    {"from":"[*]","to":"Still"},
    {"from":"Still","to":"[*]"},
    {"from":"Still","to":"Moving"},
    {"from":"Moving","to":"Still"}
  ],
  "layout":{"engine":"mermaid","direction":"TD"}
}

State diagrams emit states and transitions rather than generic components and connections.

Key Source Files for Reference

Path	Purpose
scripts/cli.mjs / archify.mjs	CLI entry point implementing archify convert
archify/src/mermaid-to-json.js	Core converter that transforms Mermaid AST to Archify IR
archify/schemas/architecture.schema.json	JSON Schema validating all Archify JSON output
examples/web-app.architecture.json	Reference fixture showing complete output structure
examples/maka-architecture.architecture.json	Complex architecture example for comparison
README_EN.md	Official CLI documentation with full parameter reference

All examples above follow the schema enforced by architecture.schema.json, ensuring compatibility across the Archify toolchain.

Consuming the Output JSON

The generated .architecture.json files integrate with:

• Archify viewer — Visualize architecture interactively
• archify test/... — Validate architecture against rules
• Custom pipelines — Process IR through your own tools

The output format is stable and versioned according to the schema definition.

Summary

• Archify CLI convert transforms Mermaid diagrams to structured JSON IR
• Three diagram types supported: flowchart (components/connections), sequence (components/messages), state (states/transitions)
• Output validates against archify/schemas/architecture.schema.json
• Key implementation lives in archify/src/mermaid-to-json.js, invoked by scripts/cli.mjs
• Reference fixtures in examples/ demonstrate real-world output structure

Frequently Asked Questions

What Mermaid diagram types does Archify support?

Archify supports flowcharts, sequence diagrams, and state diagrams as of the current tt-a1i/archify release. Each type maps to a distinct JSON structure: flowcharts use components and connections, sequence diagrams use components and messages, and state diagrams use states and transitions. Check README_EN.md for the latest supported types.

Can I convert multiple Mermaid files at once?

The archify convert command processes one file per invocation. For batch conversion, use a shell loop or build script. The CLI is designed for single-file precision to ensure each output is correctly named and validated against architecture.schema.json.

How do I validate that my output JSON is correct?

Archify JSON output automatically conforms to archify/schemas/architecture.schema.json. You can additionally run archify test path/to/file.architecture.json to validate the architecture against semantic rules and constraints defined in the toolkit.

Does the conversion preserve Mermaid styling and themes?

The converter captures structural and semantic content (nodes, edges, labels, directions) but does not preserve visual styling, CSS themes, or color definitions. The layout field in output JSON retains directional hints (TD, LR, etc.) and the source engine ("mermaid") for downstream rendering decisions.

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