ArchRay vs Mermaid, Structurizr & Eraser

Architectural diagrams only stay useful when they reflect real source code, survive scale beyond 15 nodes, and share without leaking private repository metadata.

ArchRay v0.6.0 By David Yin · Updated 2026-11-20 MIT Open Source

Choose ArchRay when you want your AI coding agent (Claude Code, Cursor, Codex, Pi, or Antigravity) to verify real source code and produce an offline, single-file 3D/2D architecture map with file:line citations and ELK port routing. Choose Mermaid for quick README snippets, Structurizr for manually governed formal C4 models, and Excalidraw for freehand whiteboarding.

Side-by-Side Architecture Tool Matrix

Different diagramming tools optimize for different parts of the software lifecycle. Generic AI diagram prompts optimize for speed on 4–6 box sketches, whereas ArchRay separates semantic source verification (done by your coding agent) from deterministic geometric layout (done offline by ELK and the ArchRay viewer engine).

CapabilityArchRay (v0.6.0)MermaidStructurizr DSLEraser / DiagramGPTExcalidraw / Draw.io
Source EvidenceVerified paths & file:line citations in graph.jsonManual / unverified textManual DSL declarationsOptional prompt upload / opaqueManual shapes
AI Coding IntegrationNative Skill + /archray for 5 AI hostsGeneric text generationExternal DSL scriptingWeb chat UI / IDE pluginManual or ad-hoc AI plugins
Deterministic LayoutELK port routing + 4-quadrant 3D atrium + 2D BentoBasic DAG / Sugiyama (tangles at >15 nodes)Auto-layout + manual coordinatesCloud layout engineManual drag & align
Layer Slicing & FilteringL0–L9 single layers + comma combos w/ 1-hop contextSeparate files requiredExplicit view scopes in DSLSingle flat canvas per diagramSeparate pages / layers
Tech Logos & Silhouettes167 embedded vector logos + semantic 3D shapesGeneric rectanglesCustom themes requiredBuilt-in cloud icon libraryManual icon packs
Health & ReplaceabilityHotspots, measured vs ≈ estimates, migration promptsNoneNoneNoneNone
Offline Privacy100% local single-file HTML (file://)Local via Markdown preview / CLIRequires local Docker/Lite server or CloudRequires SaaS serverLocal file or web storage
License & CostMIT Open Source · FreeMIT Open SourceApache 2.0 DSL / paid Cloud tiersFreemium SaaS subscriptionOpen source / freemium

Why Raw LLM Diagrams Collapse Past 15 Nodes

When an LLM writes Mermaid or raw SVG directly for a real multi-service codebase, three structural failures emerge quickly:

First, LLMs guess missing edges from directory names rather than inspecting imports or route definitions, creating plausible boxes with zero file citations. Second, client UIs, API gateways, async workers, and SQL stores share the same flat plane, producing crossed orthogonal spaghetti lines. Third, regenerating the diagram shuffles node positions completely, breaking visual memory in code reviews.

  • Semantic separation: In ArchRay, the coding agent only outputs schema-validated JSON (.archray/graph.json) containing repository-relative sourcePaths.
  • Deterministic layout: ELK computes layered coordinates, port anchors, and auto-collapses dense child packages (+N) without overlaps.
  • Auditable provenance: Numeric metrics explicitly carry origin: "measured" vs estimated (≈) markers so teams never mistake AI heuristics for live profiler telemetry.

Honest Trade-Offs: When NOT to Use ArchRay

ArchRay is built specifically for source-backed codebase topology and offline team handoffs—not every diagramming job.

  • Use Mermaid directly when you want a compact 5-step sequence diagram embedded inside a GitHub Pull Request description or Markdown README.
  • Use Structurizr when your organization enforces strict C4 Model DSL governance across enterprise workspaces with manually curated System Context diagrams.
  • Use Excalidraw or Draw.io when brainstorming unbuilt greenfield ideas where source code does not yet exist.
  • Note ArchRay boundaries: ArchRay does not attach a live runtime APM agent, capture production request traces, or run standalone AST parsing without your AI coding session.

Try ArchRay on Your Own Repository in 30 Seconds

Install ArchRay cleanly into .archray/tool without modifying any application source files, then compare the interactive output directly against your existing diagrams.

Install for Claude Code, Cursor, or all supported hosts
curl -fsSL https://github.com/loofare/ArchRay/releases/latest/download/install.sh | sh -s -- . all
# Inside a fresh coding agent session:
/archray
# Or slice specific layers after initial generation:
./.archray/archray build .archray/graph.json --layers frontend,backend,data --style blueprint --force

Frequently Asked Questions

Can ArchRay replace Mermaid inside Markdown pull requests?

They serve complementary jobs. Keep Mermaid for tiny inline PR sequence flows, and attach an ArchRay full-canvas PNG export or .archray/index.html artifact when reviewing whole-service architecture, cross-layer dependencies, or migration plans.

Does ArchRay support C4-style hierarchical drill-down like Structurizr?

Yes. ArchRay Graph v2 models flat nodes with parent references so complex domains group cleanly, auto-collapse with +N badges at overview zoom, and expand interactively without writing C4 DSL by hand.

Why does ArchRay produce both 3D Spatial Atrium and 2D Bento maps?

3D Spatial Atrium separates Client/Edge, Central Services, Async/AI Left Wing (-X), External SaaS Right Orbit (+X), and Data/Infra Plinth vertically so deep cross-layer paths stand out. Switching to 2D Bento flattens the exact same verified graph into clean print-ready containment boxes.

Does ArchRay upload source code to archray.dev or any SaaS server?

Never. Analysis occurs exclusively inside the AI coding session you already authorize. CLI build runs offline and produces a self-contained HTML file that works over file://.

Can I keep graph.json under version control like code?

Yes. Many teams commit .archray/graph.json (and view.json) so architecture changes remain diffable in Git alongside application code, while regenerating .archray/index.html locally.

Try ArchRay on your repository in 30 seconds

100% local CLI and single-file offline HTML across Claude Code, Cursor, Antigravity, Pi, and Codex.

Related Guides & Reference