# How Archify Maps Mermaid Diagram Types to Its Native Types

> Discover how Archify transforms Mermaid diagrams into its native types. Archify infers diagram intent via prompt engineering for a unique JSON representation, not direct rendering.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-09-02

---

**Archify treats Mermaid syntax as an input dialect and uses prompt-engineering to infer the diagram's logical intent, then generates a fresh Archify JSON representation rather than rendering Mermaid's native output.**

When working with Mermaid diagrams in the **tt-a1i/archify** repository, understanding how Mermaid diagram types map to Archify's native types is essential for generating consistent, branded visualizations. Archify does not act as a Mermaid renderer—instead, it extracts semantic meaning from Mermaid source code and reconstructs the diagram using Archify's own layout engines.

## The Core Mapping Strategy

The mapping logic is defined in **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** (lines 67-74) and follows a semantic translation approach. Archify reads the Mermaid topology, extracts its underlying graph structure, and author-writes a new Archify JSON specification that Archify's renderer pipelines then visualize.

| Mermaid construct | Archify diagram type | Translation behavior |
|-------------------|----------------------|----------------------|
| `flowchart` / `graph` | **`workflow`** (or `architecture` for component maps) | Process flows become Archify workflow diagrams with full layout control |
| `sequenceDiagram` | **`sequence`** | Participants and messages map to Archify's sequence diagram primitives |
| `stateDiagram` | **`lifecycle`** | States and transitions preserved, rendered with Archify's lifecycle styling |

## Flowchart and Graph Mapping to Workflow

Mermaid's `flowchart` and `graph` declarations transform into Archify's **`workflow`** type. For diagrams describing system components or deployments, Archify may select **`architecture`** instead.

The `workflow` renderer expects a specific JSON contract defined in **[`archify/renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/workflow/README.md)**. Generated output separates nodes and edges into a structured list that Archify's layout engine processes independently of Mermaid's auto-layout decisions.

```bash

# Create a Mermaid flowchart

cat <<'EOF' > my-flow.mmd
graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Do task]
  B -->|No| D[Abort]
EOF

# Archify infers type → workflow and generates JSON

node bin/archify.mjs guide "my-flow.mmd" --json

# → Returns {"type":"workflow", nodes: [...], edges: [...]}

```

The CLI produces a JSON artifact ready for validation and delivery:

```bash
node bin/archify.mjs deliver workflow my-flow.json output.html

```

## SequenceDiagram Mapping to Sequence

Mermaid `sequenceDiagram` blocks map directly to Archify's **`sequence`** type. The prompt-engineering layer identifies `participant` declarations and message arrows (`->>`, `-->>`, etc.), then reconstructs them using Archify's sequence renderer contract.

```bash

# Define a Mermaid sequence diagram

cat <<'EOF' > my-seq.mmd
sequenceDiagram
  participant Alice
  participant Bob
  Alice->>Bob: Hello
  Bob-->>Alice: Hi
EOF

# Generate Archify sequence JSON

node bin/archify.mjs guide "my-seq.mmd" --json

# → Returns {"type":"sequence", participants: [...], messages: [...]}

```

The output conforms to the layout contract in **[`archify/renderers/sequence/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/sequence/README.md)**, ensuring consistent message ordering and participant alignment across all Archify-generated sequence diagrams.

## StateDiagram Mapping to Lifecycle

Mermaid `stateDiagram` declarations translate to Archify's **`lifecycle`** type. This preserves all state nodes and transition edges while applying Archify's native lifecycle visual styling rather than Mermaid's state diagram aesthetics.

```bash

# Define a Mermaid state diagram

cat <<'EOF' > my-state.mmd
stateDiagram
  [*] --> Idle
  Idle --> Active
  Active --> [*]
EOF

# Archify maps to lifecycle type

node bin/archify.mjs guide "my-state.mmd" --json

# → Returns {"type":"lifecycle", states: [...], transitions: [...]}

```

The lifecycle renderer contract in **[`archify/renderers/lifecycle/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/lifecycle/README.md)** specifies how states render and how transitions display, maintaining brand consistency across all state-machine visualizations.

## Why Archify Reconstructs Rather Than Renders

The strategic decision to treat Mermaid as an **input dialect** rather than implementing a Mermaid parser is documented in **[`ROADMAP.md`](https://github.com/tt-a1i/archify/blob/main/ROADMAP.md)** (lines 98-106). This architectural choice ensures:

- **Layout control** — Archify's engines determine positioning, not Mermaid's auto-layout
- **Brand consistency** — All output follows Archify's design system
- **Information architecture** — Semantic structure can be enhanced or restructured during translation
- **Render pipeline unification** — Single rendering stack for all diagram sources

No Mermaid parser runs at runtime. The mapping logic resides entirely in the skill description layer, making the translation transparent and maintainable.

## Summary

- Archify maps Mermaid `flowchart`/`graph` to **`workflow`** or **`architecture`** types based on intent
- Mermaid `sequenceDiagram` maps to Archify's **`sequence`** type with full participant/message reconstruction
- Mermaid `stateDiagram` translates to Archify's **`lifecycle`** type with state/transition preservation
- The mapping definitions live in **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)**
- Translation happens through prompt-engineering, not parsing—no Mermaid renderer is invoked
- Generated JSON conforms to renderer contracts in **`archify/renderers/{type}/README.md`**

## Frequently Asked Questions

### Does Archify render Mermaid diagrams directly?

No. Archify reads Mermaid source code through its prompt-engineering layer, extracts the semantic graph structure, and generates a new Archify JSON specification. The actual rendering uses Archify's native engines, not Mermaid's layout algorithms.

### Where is the Mermaid-to-Archify mapping defined?

The complete mapping specification resides in **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** at lines 67-74. This skill file defines how each Mermaid construct translates to Archify diagram types and what authoring invariants must hold.

### Can I customize how Archify interprets my Mermaid diagram?

The interpretation follows the fixed mapping in the skill file. However, you can influence the output type—for example, a component-focused `graph` declaration may generate an **`architecture`** type instead of **`workflow`**, depending on how the prompt-engineering layer classifies the semantic intent.

### How do I convert a Mermaid file to Archify's JSON format?

Use the Archify CLI `guide` command with the `--json` flag: `node bin/archify.mjs guide "your-file.mmd" --json`. This produces a type-tagged JSON file ready for the `deliver` command to render as HTML.