Skip to content
loofarePublic

About

AI-first 3D/2D architecture visualizer for Claude Code, Cursor, Codex, Pi & Antigravity — turns real source code into offline single-file HTML maps with file:line evidence.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

ArchRay

ArchRay

Equip your AI coding agent to read real source code and build interactive, 100% offline 3D Spatial & 2D Bento architecture maps.

Version v0.6.0 License MIT Node.js 20+ 100% Offline Single HTML archray.dev

English · 简体中文 · Website · Live 3D Sandbox · Guides · Compare Tools


ArchRay 3D Spatial Atrium Live Demo — FreshMart Commerce (5 layers, 16 modules, 19 directed edges)

Captured live from archray.dev/demo: interactive 3D Spatial Atrium, 2D Bento map, Health Hotspots, and Replaceability views—click to explore live.


Core Engineering Capabilities

 True 3D Spatial Atrium + 2D Bento Map

VisionOS-style floating HUD powered by deterministic ELK port routing, separating client surfaces, central service spines, async/AI wings (-X), external SaaS orbits (+X), and storage plinths.

 Verified Source Evidence & Honest Provenance

Every node and dependency cites repository sourcePaths; numeric metrics cleanly distinguish direct measurements (measured) from static estimates (≈)—never faking live APM telemetry.

 Health Hotspots & Replaceability Prompts

Surface coupling bottlenecks and lock-in risk, compare drop-in OSS or managed alternatives by effort/risk, and copy ready-to-run AI migration prompts back to your coding agent.

 Zero-Network Single-File HTML

Emits a self-contained .archray/index.html (opens directly via file://) bundling 167 embedded vector tech logos, unclipped full-canvas PNG export, and offline QR share posters.


How It Works: Separating Semantics from Deterministic Layout

LLMs excel at reading repository structure and control flow—but collapse into crossed edges when hand-authoring SVG coordinates or raw diagrams. ArchRay decouples semantic extraction from layout math:

ArchRay 4-stage pipeline: Real Source Repo -> AI Coding Agent (/archray) -> Deterministic ELK -> Offline Single HTML

View Gallery: Four Inspection Lenses on One Verified Graph

Analyze source once into .archray/graph.json, then switch projections, health diagnostics, and shareable exports with zero extra LLM calls:

ArchRay 2D Bento Map View
2D Bento Map
L0–L4 deterministic containment layers, adaptive reflow & live minimap
ArchRay Health Hotspots Lens
Health Hotspots Lens
Highlights critical hotspots (6.2k LOC sync lock) with measured vs ≈ labels
ArchRay Replaceability & AI Migration Prompts
Replaceability & Migration Prompts
Compare Passport → Clerk / Keycloak options with downstream impact preview
ArchRay Unclipped PNG Export & Offline QR Poster
Unclipped PNG & Offline QR Poster
Full world-bounds PNG projection & zero-network QR cards for team handoffs

1. 30-Second Install & First Map

Requirements: Node.js 20+, curl, and tar (on Windows, run the installer inside Git Bash or WSL; it emits .archray\archray.cmd).

One-Line Install in Target Repository Root

curl -fsSL https://github.com/loofare/ArchRay/releases/latest/download/install.sh | sh -s -- . claude

Replace claude with your AI host (comma-separated lists like claude,cursor or all are supported):

AI Host Argument Session Trigger Host Files Written
Claude Code  Claude Code claude /archray, /archray:frontend, … .claude/skills/archray/, .claude/commands/
Cursor  Cursor cursor /archray, /archray-frontend, … .cursor/rules/archray.mdc, .cursor/commands/
Antigravity  Antigravity antigravity /archray or Skill trigger .agent/skills/archray/, .agent/commands/
Pi  Pi pi /archray, /archray-frontend, /skill:archray .agents/skills/archray/, .pi/prompts/
Codex  Codex codex $archray or /skills .agents/skills/archray/SKILL.md
Prefer letting your AI coding assistant run setup? Paste this prompt
Download https://github.com/loofare/ArchRay/releases/latest/download/install.sh to a temporary file, verify it succeeded, and run `sh <temp-file> . claude` from this repo root (replace claude with your host).

Generate Your First Map

  1. Open a fresh AI coding session in the repository.
  2. Run /archray ($archray on Codex), or simply ask: “Use archray to inspect source code and build a 3D map”.
  3. Open .archray/index.html directly in any browser.

2. L0–L9 Spatial Layers & Instant Slicing

Once .archray/graph.json is generated, slice any single layer or comma-separated cross-layer path on demand—direct one-hop neighbors remain softly dimmed for context:

ArchRay L0-L9 Spatial 4-Quadrant Zoning & CLI Layer Slicing
Goal Slash Command / Args What It Focuses
View All (Default) /archray or /archray:full All 10 architectural layers (L0–L9)
Frontend /archray:frontend or /archray frontend L0 client web apps, mobile & UI surfaces
Backend + Async /archray:backend or /archray backend L3 service domain APIs + L4 async queues/workers
Data & Storage /archray:data or /archray data L5 data SQL databases, Redis caches, search & S3
Network & Edge /archray:network or /archray network L1 edge + L2 gateway CDN, WAF & ingress
Security & Auth /archray:security or /archray security L2 gateway OAuth/OIDC, JWT guards & rate limits
Cross-Layer Combos /archray frontend,backend
/archray backend,data
/archray ai,async,data
Combine any layers with commas (EN & ZH aliases work)
Theme & Locale --style blueprint --lang en Themes: tech / blueprint / glass / paper
Update / Uninstall /archray update / /archray uninstall Safely keeps graph.json, view.json, and HTML

3. Verified Monorepo Benchmarks & Tool Comparison

Tested on real engineering repositories—confirming non-overlapping ELK layouts, +N auto-collapsing on dense monorepos, and v0.6.0 UTF-8 without BOM enforcement:

Benchmark Repository Scale & Topology Build / Layout Speed Verified Highlights
calcom/cal.com (ae027bb) 7,712 tracked files → 33 modules · 75 edges · 7 layers 196ms Node ELK layout Dense packages fold (+N), 60fps 3D orbit
FreshMart Commerce (Live Demo) 16 modules · 19 edges · 5 layers · Checkout flow Instant single-file HTML Surfaces 6.2k LOC lock hotspot & Clerk migration plan
SaaS Starter & RealWorld 43–49 source files 0.03s CLI build Maps App Router/Prisma/Stripe, flags JWT_SECRET fallback

4. CLI & Maintenance (From Repo Root)

Self-contained wrapper inside .archray/ with zero global pollution (.archray\archray.cmd on Windows):

./.archray/archray doctor                                      # Check packaged assets & Node version
./.archray/archray validate .archray/graph.json                # Validate TypeBox schema, locales & UTF-8
./.archray/archray build .archray/graph.json --force --no-open # Rebuild single-file offline HTML
./.archray/archray build .archray/graph.json --layers frontend,data --style blueprint --force

Upgrade & Uninstall:

./.archray/archray update --check       # Check latest release without modifying files
./.archray/archray update               # Verify SHA-256 & update (keeps graph/view/HTML)

./.archray/archray uninstall --dry-run  # Preview files to be removed
./.archray/archray uninstall            # Remove tool & host commands (keeps graph/view/HTML)
./.archray/archray uninstall --purge    # Remove the entire .archray/ directory
One-time upgrade from v0.4.0 or earlier
curl -fsSL https://github.com/loofare/ArchRay/releases/latest/download/install.sh | sh -s -- . auto --force

5. Privacy & Honest Boundaries

Note

100% Local · Zero Source Upload · Verifiable Provenance

  • ArchRay CLI and generated .archray/index.html views run completely offline over file://; source code, paths, and graphs never leave your machine (analysis happens solely inside your authorized coding-agent session).
  • Not a SaaS scanner or live APM agent; sourcePaths, health findings, and replacement candidates are static review claims to verify against code.
  • Only an explicit update contacts GitHub Releases read-only to check latest.json and verify SHA-256 archives.

See Host Compatibility · Changelog · NOTICE · MIT License · archray.dev.

About

AI-first 3D/2D architecture visualizer for Claude Code, Cursor, Codex, Pi & Antigravity — turns real source code into offline single-file HTML maps with file:line evidence.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages