How Archify Maps Mermaid Diagram Types to Its Native Types

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 (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. Generated output separates nodes and edges into a structured list that Archify's layout engine processes independently of Mermaid's auto-layout decisions.

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

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.

# 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, 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.

# 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 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 (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
• 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 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.

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