L0–L9 Layers, Node Kinds & Graph v2 Reference
Technical lookup for ArchRay’s canonical 10-layer taxonomy, deterministic 3D spatial zoning, node kinds, edge protocols, themes, and CLI subcommands.
ArchRay Graph v2 organizes architecture into 10 canonical layers (`client`, `edge`, `gateway`, `service`, `async`, `data`, `ai`, `external`, `platform`, `observability`), 19 node kinds, and 14 edge protocols rendered across 4 visual themes (`tech`, `blueprint`, `glass`, `paper`) with 167 embedded vector logos and 212 technology classification hints.
1. The 10 Canonical Architectural Layers (L0–L9)
Assigning a node to a canonical layer places it in a deterministic 3D zone (and clean Bento row in 2D) while unlocking single-layer and comma-separated CLI filtering with English or Chinese aliases:
| Band | Canonical ID | CLI / Slash Aliases | 3D Spatial Role & Silhouette | Representative Tech |
|---|---|---|---|---|
| L0 | client | frontend, client, 前端, 客户端 | Top Atrium · Tilted Screen Slab | Next.js, Vue 3, React Native, Electron |
| L1 | edge | network, edge, 网络, 边缘 | Upper Ingress Buffer · Wide Slab | Cloudflare, Nginx, Envoy, Traefik |
| L2 | gateway | security, gateway, 网关, 鉴权 | Auth Hub · Gateway Prism | Kong, Better Auth, Clerk, Keycloak |
| L3 | service | service, backend, 后端, 服务 | Central Spine · Rounded Service Slab | NestJS, FastAPI, Spring Boot, Go |
| L4 | async | async, worker, 异步, 队列 | Left Wing (-X) · Capsule Worker | Kafka, BullMQ, Socket.IO, Celery |
| L5 | data | data, db, 数据, 存储 | Storage Plinth · Segmented Cylinder | PostgreSQL, Redis, Elasticsearch, S3 |
| L6 | ai | ai, model, AI, 智能 | AI Wing (-X) · Inference Core | Gemini, Claude, Qdrant, pgvector |
| L7 | external | external, saas, 外部, 三方 | Right Orbit (+X) · Dashed Satellite | Stripe, Resend, Twilio, OAuth SaaS |
| L8 | platform | platform, infra, 平台, 运维 | Infra Base · Foundation Plate | Docker, Kubernetes, Terraform, Actions |
| L9 | observability | observability, obs, 可观测, 监控 | Telemetry Base · Plane | OpenTelemetry, Prometheus, Grafana, Sentry |
2. 19 Known Node Kinds & 14 Protocols
Known technologies (212 entries in `knowledge/tech.json`) resolve automatically against 167 embedded vector brand logos; unknown or custom components fall back crisply to role-based kind silhouettes:
- 19 known node kinds: `client`, `cli`, `gateway`, `service`, `worker`, `function`, `library`, `module`, `database`, `cache`, `queue`, `storage`, `search`, `external-api`, `ai-model`, `config`, `group`, `saas`, `archive` (custom strings also permitted).
- 14 known edge protocols: `http`, `grpc`, `graphql`, `ws`, `sse`, `amqp`, `kafka`, `sql`, `redis`, `ipc`, `import`, `fs`, `llm`, `event`.
- 4 visual themes (`--style`): `tech` (default deep studio), `blueprint` (architectural cyan), `glass` (translucent frost), `paper` (high-contrast print light).
- 3 motion presets (`--motion`): `full`, `calm`, `off` (respecting `prefers-reduced-motion`).
3. Minimal Graph v2 JSON Example
AI coding agents write semantic facts only—zero pixel coordinates are ever authored by hand in `.archray/graph.json`:
{
"schemaVersion": "2.0",
"meta": { "name": { "en": "Acme App", "zh-CN": "Acme 应用" }, "locales": ["en", "zh-CN"], "generatedAt": "2026-11-20T00:00:00Z" },
"layers": [
{ "id": "client", "name": { "en": "Client", "zh-CN": "客户端" }, "order": 0 },
{ "id": "service", "name": { "en": "Services", "zh-CN": "业务服务" }, "order": 3 },
{ "id": "data", "name": { "en": "Data", "zh-CN": "数据存储" }, "order": 5 }
],
"nodes": [
{ "id": "web", "layer": "client", "kind": "client", "name": { "en": "Web App", "zh-CN": "Web 前端" }, "sourcePaths": ["apps/web/src/app/page.tsx"] },
{ "id": "api", "layer": "service", "kind": "service", "name": { "en": "Order API", "zh-CN": "订单服务" }, "sourcePaths": ["apps/api/src/order.ts"] },
{ "id": "pg", "layer": "data", "kind": "database", "name": { "en": "PostgreSQL", "zh-CN": "PostgreSQL 主库" }, "tech": ["PostgreSQL"], "sourcePaths": ["prisma/schema.prisma"] }
],
"edges": [
{ "id": "e1", "from": "web", "to": "api", "protocol": "http" },
{ "id": "e2", "from": "api", "to": "pg", "protocol": "sql" }
]
}
4. Complete CLI Command Reference
Run from the target repository root using `./.archray/archray` (or `.archray\archray.cmd` on Windows):
| Command | Purpose & Key Flags |
|---|---|
| ./.archray/archray doctor | Verify Node.js 20+, bundled assets, schemas & icon packs |
| ./.archray/archray validate .archray/graph.json | Validate TypeBox schema, unique IDs, locale parity & UTF-8 integrity |
| ./.archray/archray build <graph.json> [flags] | Compile single-file HTML (--layers, --style, --lang, --motion, --output, --force, --no-open) |
| ./.archray/archray update [--check] | Read-only check or SHA-256 verified tool update preserving graph/view/index |
| ./.archray/archray uninstall [--dry-run] [--purge] | Preview or cleanly remove adapters and optionally `.archray/` artifacts |
Frequently Asked Questions
Do I have to use all 10 canonical layers on every repository?
No. Recommended maps declare 3–6 layers that actually exist in your repository (e.g., FreshMart declares 5 layers), while the CLI still maps nodes accurately into the L0–L9 taxonomy.
How are child modules grouped under a parent node?
Set `parent: "<parent-id>"` on child nodes inside the flat `nodes` array with globally unique IDs (e.g., `order/repo`). At overview zoom they auto-collapse cleanly into `+N` badges.
Can I save a customized camera angle and filter state?
Yes. Use `view.json` import/export right inside the viewer top bar to save or share exact layer toggles, lens modes, theme selection, and camera coordinates.
How many brand icons ship offline inside each built HTML file?
167 vector brand icons derived from `@iconify-json/logos` paired with 212 technology classification rules in `knowledge/tech.json`—loaded with zero CDN calls.
Try ArchRay on your repository in 30 seconds
100% local CLI and single-file offline HTML across Claude Code, Cursor, Antigravity, Pi, and Codex.