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.
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).
| Capability | ArchRay (v0.6.0) | Mermaid | Structurizr DSL | Eraser / DiagramGPT | Excalidraw / Draw.io |
|---|---|---|---|---|---|
| Source Evidence | Verified paths & file:line citations in graph.json | Manual / unverified text | Manual DSL declarations | Optional prompt upload / opaque | Manual shapes |
| AI Coding Integration | Native Skill + /archray for 5 AI hosts | Generic text generation | External DSL scripting | Web chat UI / IDE plugin | Manual or ad-hoc AI plugins |
| Deterministic Layout | ELK port routing + 4-quadrant 3D atrium + 2D Bento | Basic DAG / Sugiyama (tangles at >15 nodes) | Auto-layout + manual coordinates | Cloud layout engine | Manual drag & align |
| Layer Slicing & Filtering | L0–L9 single layers + comma combos w/ 1-hop context | Separate files required | Explicit view scopes in DSL | Single flat canvas per diagram | Separate pages / layers |
| Tech Logos & Silhouettes | 167 embedded vector logos + semantic 3D shapes | Generic rectangles | Custom themes required | Built-in cloud icon library | Manual icon packs |
| Health & Replaceability | Hotspots, measured vs ≈ estimates, migration prompts | None | None | None | None |
| Offline Privacy | 100% local single-file HTML (file://) | Local via Markdown preview / CLI | Requires local Docker/Lite server or Cloud | Requires SaaS server | Local file or web storage |
| License & Cost | MIT Open Source · Free | MIT Open Source | Apache 2.0 DSL / paid Cloud tiers | Freemium SaaS subscription | Open 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.
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.