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 v0.6.0 By David Yin · Updated 2026-11-20 MIT Open Source

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:

BandCanonical IDCLI / Slash Aliases3D Spatial Role & SilhouetteRepresentative Tech
L0clientfrontend, client, 前端, 客户端Top Atrium · Tilted Screen SlabNext.js, Vue 3, React Native, Electron
L1edgenetwork, edge, 网络, 边缘Upper Ingress Buffer · Wide SlabCloudflare, Nginx, Envoy, Traefik
L2gatewaysecurity, gateway, 网关, 鉴权Auth Hub · Gateway PrismKong, Better Auth, Clerk, Keycloak
L3serviceservice, backend, 后端, 服务Central Spine · Rounded Service SlabNestJS, FastAPI, Spring Boot, Go
L4asyncasync, worker, 异步, 队列Left Wing (-X) · Capsule WorkerKafka, BullMQ, Socket.IO, Celery
L5datadata, db, 数据, 存储Storage Plinth · Segmented CylinderPostgreSQL, Redis, Elasticsearch, S3
L6aiai, model, AI, 智能AI Wing (-X) · Inference CoreGemini, Claude, Qdrant, pgvector
L7externalexternal, saas, 外部, 三方Right Orbit (+X) · Dashed SatelliteStripe, Resend, Twilio, OAuth SaaS
L8platformplatform, infra, 平台, 运维Infra Base · Foundation PlateDocker, Kubernetes, Terraform, Actions
L9observabilityobservability, obs, 可观测, 监控Telemetry Base · PlaneOpenTelemetry, 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`:

Minimal bilingual v2 node & edge structure (.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):

CommandPurpose & Key Flags
./.archray/archray doctorVerify Node.js 20+, bundled assets, schemas & icon packs
./.archray/archray validate .archray/graph.jsonValidate 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.

Related Guides & Reference