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.
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 Created | Purpose | Source Code Touched? |
|---|---|---|
| .claude/skills/archray/ | Claude Code skill rules & v2 schema prompt | No |
| .claude/commands/archray*.md | Slash presets (/archray, /archray:frontend, etc.) | No |
| .archray/tool/ & .archray/archray | Self-contained CLI, ELK engine & viewer bundle | No |
| .archray/graph.json & index.html | Generated graph facts & offline HTML (after /archray) | No |
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 Command | Canonical Layers Highlighted | When to Use |
|---|---|---|
| /archray or /archray:full | All present layers (L0–L9) | Initial full-repository onboarding & architecture review |
| /archray:frontend | client (L0) | Web SPA/SSR, mobile, and desktop UI surfaces + 1-hop APIs |
| /archray:backend | service + async (L3 + L4) | Core domain services, RPC handlers, queues & background workers |
| /archray:data | data (L5) | PostgreSQL, Redis caches, search indices & object stores |
| /archray:network | edge + gateway (L1 + L2) | CDN, WAF, reverse proxies & ingress gateway routing |
| /archray:security | gateway (L2) | OAuth/OIDC auth boundaries, JWT guards & rate limiting |
| /archray frontend,backend | Comma-separated custom combo | Trace 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.