Limitations of Archify: 7 Hard Constraints You Should Know

Archify intentionally rejects generic drawing capabilities—such as Mermaid parsing, auto-layout engines, and WYSIWYG editing—to guarantee that every architecture diagram is deterministically generated from typed JSON and fully traceable to its source.

Archify is a deterministic, typed-JSON-driven architecture diagram generator maintained in the tt-a1i/archify repository. While it produces self-contained HTML/SVG artifacts suitable for trustworthy documentation, the tool enforces strict functional boundaries that distinguish it from general-purpose drawing applications. Understanding these limitations helps teams decide when Archify fits their workflow and when a generic tool might be necessary.

The 7 Hard Limits of Archify

No Automatic Mermaid Parsing

Archify never accepts free-form Mermaid syntax and will not convert it into a validated diagram. As documented in [README_EN.md](https://github.com/tt-a1i/archify/blob/main/README_EN.md), automatic Mermaid parsing is explicitly outside the current scope. The CLI validates input strictly and rejects any attempt to feed it raw Mermaid text.

# This will fail because Archify expects JSON IR, not Mermaid.

node archify/bin/archify.mjs render architecture <<EOF
graph LR
  A --> B
EOF

Result (stderr):

Error: Input must be a typed JSON IR file; Mermaid syntax is not accepted.

No General-Purpose Auto-Layout

Layout is a choice made by the LLM-agent; Archify never runs a generic graph-layout engine (e.g., Graphviz) to reposition nodes automatically. According to the same section in README_EN.md, agent-chosen layout is the only supported method. Commands requesting external layout algorithms are rejected to preserve deterministic output.

node archify/bin/archify.mjs render architecture my-diagram.json --layout graphviz

Result (stderr):

Error: Layout option "graphviz" is not supported. Archify uses agent-chosen layout only.

No Hosted Sharing Service

While Archify produces self-contained HTML/SVG artifacts that can be hosted anywhere, the repository itself does not provide a public image-hosting endpoint. Users must deploy outputs to their own infrastructure, static hosting platforms, or documentation systems. There is no SaaS component for sharing diagrams via public URLs.

No WYSIWYG Editor

There is no in-browser drag-and-drop editor. All edits must be expressed as typed JSON or through LLM-generated prompts. This constraint ensures that every visual change is explicitly represented in the intermediate representation (IR) and remains under version control, eliminating hidden state that cannot be diffed or reviewed.

Scope-Limited Validation

Validation checks only the typed JSON IR—including schema, layout, route, and label-to-route mappings. As noted in [CHANGELOG.md](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md), the tool never inspects live infrastructure, runtime performance, or security posture beyond what the author explicitly models. Archify cannot detect drift between your diagram and actual deployed cloud resources.

No Runtime Code Execution

Archify never executes arbitrary code, runs builds, or contacts external APIs—with one exception. The CLI includes a single optional update-check that can be disabled. According to README_EN.md, you can disable this network call via the ARCHIFY_UPDATE_CHECK_DISABLED environment variable.

# Normal behaviour – a one-second network request may be made.

node archify/bin/archify.mjs doctor

# Disable it permanently.

export ARCHIFY_UPDATE_CHECK_DISABLED=1
node archify/bin/archify.mjs doctor   # No network traffic performed.

No Support for Custom Diagram Types

Only five built-in diagram types are supported: Architecture, Workflow, Sequence, Data Flow, and Lifecycle. As defined in [archify/SKILL.md](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), adding a new visual preset requires a code change in the renderer library. The CLI validates types strictly against this fixed set.

node archify/bin/archify.mjs render my-custom-type my-diagram.json

Result (stderr):

Error: Diagram type "my-custom-type" is not recognized. Supported types are architecture, workflow, sequence, dataflow, lifecycle.

Why These Constraints Exist by Design

These limitations are intentional architectural decisions rather than missing features. Archify's value proposition centers on trust-worthy, reproducible communication. By refusing to infer topology from free-form text, perform live infrastructure analysis, or expose uncontrolled editing surfaces, the tool guarantees that every published artifact is fully traceable to the typed JSON source that produced it. This deterministic pipeline eliminates "works on my machine" scenarios for architecture diagrams and ensures that renders are identical across different environments when given the same IR.

Summary

• Archify rejects Mermaid syntax and requires typed JSON IR input exclusively.
• No auto-layout engines like Graphviz are supported; layout is agent-determined and encoded in the IR.
• No hosted service is provided; users self-host HTML/SVG outputs on their own infrastructure.
• No visual editor exists; all changes require JSON editing or LLM prompts.
• Validation is limited to the JSON IR and does not inspect live systems or security posture.
• No arbitrary code execution occurs, with only an optional update-check that can be disabled via environment variable.
• Only five diagram types are supported, with no runtime extension mechanism for custom visuals.

Frequently Asked Questions

Can Archify render Mermaid syntax directly?

No. Archify explicitly refuses free-form Mermaid syntax. As implemented in tt-a1i/archify, the CLI validates that input is a typed JSON IR file and returns an error if Mermaid text is detected at line 76 of README_EN.md. You must convert Mermaid diagrams to Archify's JSON schema before rendering.

Does Archify support custom diagram types beyond the built-in five?

No. According to archify/SKILL.md, only Architecture, Workflow, Sequence, Data Flow, and Lifecycle types are recognized. Attempting to specify a custom type results in a CLI validation error referencing the supported list. Adding new types requires modifying the renderer library source code and rebuilding the tool.

Can I use a WYSIWYG editor to modify Archify diagrams?

No. Archify does not provide an in-browser drag-and-drop editor or canvas manipulation interface. All modifications must be made to the typed JSON intermediate representation or generated via LLM prompts. This design ensures complete traceability between the source data and the rendered output, supporting proper version control workflows.

Does Archify automatically adjust node positions using graph layout algorithms?

No. Archify does not run generic graph-layout engines such as Graphviz or forced-directed algorithms. Layout decisions are made by the LLM-agent and encoded in the JSON IR. The CLI will reject commands requesting external layout engines, confirming that agent-chosen layout is the only supported method.

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