Claude Code Architecture Diagram Guide

Turn Claude Code from a text-first coding assistant into an evidence-backed spatial architect with a single /archray slash command.

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

Install ArchRay targeting Claude Code once in your repo root (`sh -s -- . claude`), start a fresh Claude Code session, and run `/archray`. Claude reads real source files into `.archray/graph.json`, runs deterministic validation and ELK layout, and emits a zero-dependency `.archray/index.html` you can slice by layer (`/archray:frontend`, `/archray backend,data`) without re-scanning.

1. Install ArchRay for Claude Code

Run the self-contained installer from the root directory of the repository you want to map. Node.js 20+, curl, and tar are required (on Windows, use Git Bash or WSL). Application source code is never modified.

Artifact CreatedPurposeSource Code Touched?
.claude/skills/archray/Claude Code skill rules & v2 schema promptNo
.claude/commands/archray*.mdSlash presets (/archray, /archray:frontend, etc.)No
.archray/tool/ & .archray/archraySelf-contained CLI, ELK engine & viewer bundleNo
.archray/graph.json & index.htmlGenerated graph facts & offline HTML (after /archray)No
Run in target repository root
curl -fsSL https://github.com/loofare/ArchRay/releases/latest/download/install.sh | sh -s -- . claude

2. Available Claude Code Slash Commands

Open a new Claude Code session after installation so `.claude/commands/` is discovered cleanly. Type `/archray` for the full 10-layer map, or slice straight into specific subsystems once `.archray/graph.json` exists.

Slash CommandCanonical Layers HighlightedWhen to Use
/archray or /archray:fullAll present layers (L0–L9)Initial full-repository onboarding & architecture review
/archray:frontendclient (L0)Web SPA/SSR, mobile, and desktop UI surfaces + 1-hop APIs
/archray:backendservice + async (L3 + L4)Core domain services, RPC handlers, queues & background workers
/archray:datadata (L5)PostgreSQL, Redis caches, search indices & object stores
/archray:networkedge + gateway (L1 + L2)CDN, WAF, reverse proxies & ingress gateway routing
/archray:securitygateway (L2)OAuth/OIDC auth boundaries, JWT guards & rate limiting
/archray frontend,backendComma-separated custom comboTrace end-to-end feature calls while dimming peripheral infra

3. Best Practices & Windows UTF-8 Reliability

Because Claude Code inspects real files before generating `.archray/graph.json`, results improve significantly when you verify two habits:

  • Always verify with `./.archray/archray doctor` if Claude cannot find the CLI binary after moving folders.
  • On Windows PowerShell, avoid piping JSON through Out-File or Set-Content without UTF-8 encoding; ArchRay v0.6.0 guides Claude to use native UTF-8 file writes without BOM and automatically flags any accidental ? placeholder corruption during `validate`.
  • Re-style offline at zero LLM token cost: run `./.archray/archray build .archray/graph.json --style blueprint --lang en --force` in your terminal to switch between tech, blueprint, glass, and paper themes.

Frequently Asked Questions

Do I have to re-install ArchRay for every repository?

Install once per target repository root so `.archray/` and `.claude/` stay scoped cleanly to that repo without polluting global Node modules or unrelated projects.

Why must I open a new Claude Code session after running install.sh?

Claude Code scans `.claude/commands/` and skills when starting a session. Opening a fresh session guarantees `/archray` and its preset variants appear in autocomplete.

Does `/archray frontend,data` re-read the entire codebase with tokens?

Once `.archray/graph.json` is built, slicing layers runs deterministically in seconds through `./.archray/archray build --layers ...`—no extra full-repo re-scan required.

How do I remove ArchRay from a repository cleanly?

Run `./.archray/archray uninstall --dry-run` to inspect all host files to remove, then `uninstall` (keeps your generated maps) or `uninstall --purge` (removes `.archray/` completely).

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