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

> Easily convert Mermaid diagrams like flowcharts sequence and state diagrams to Archify JSON using the Archify CLI convert command. Streamline your architecture documentation.

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

---

**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:

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

## How the Conversion Works

Under the hood, the conversion pipeline follows three stages as implemented in [`archify/src/mermaid-to-json.js`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)

The resulting structure matches real-world fixtures like [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json) and [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json).

## Conversion Examples by Diagram Type

### Flowchart to Archify JSON

Save this as `flowchart.mmd`:

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

```

Run the conversion:

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

```

Generated [`flowchart.architecture.json`](https://github.com/tt-a1i/archify/blob/main/flowchart.architecture.json):

```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`:

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

```

Run the conversion:

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

```

Generated [`conversation.architecture.json`](https://github.com/tt-a1i/archify/blob/main/conversation.architecture.json):

```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`:

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

```

Run the conversion:

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

```

Generated [`states.architecture.json`](https://github.com/tt-a1i/archify/blob/main/states.architecture.json):

```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`](https://github.com/tt-a1i/archify/blob/main/archify/src/mermaid-to-json.js) | Core converter that transforms Mermaid AST to Archify IR |
| [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | JSON Schema validating all Archify JSON output |
| [`examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json) | Reference fixture showing complete output structure |
| [`examples/maka-architecture.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/maka-architecture.architecture.json) | Complex architecture example for comparison |
| [`README_EN.md`](https://github.com/tt-a1i/archify/blob/main/README_EN.md) | Official CLI documentation with full parameter reference |

All examples above follow the schema enforced by [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), ensuring compatibility across the Archify toolchain.

## Consuming the Output JSON

The generated [`.architecture.json`](https://github.com/tt-a1i/archify/blob/main/.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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)
- **Key implementation** lives in [`archify/src/mermaid-to-json.js`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json).

### How do I validate that my output JSON is correct?

Archify JSON output automatically conforms to [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/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.