# Draw JSON Architecture

> Draws an interactive HTML Architecture Viewer for any code flow the user names. Walks through seven research-driven steps (flow, name, repo research, lens colors, evidence flags, lens+mechanism per stop, build) and verifies links, claims, and generated artifacts before delivery.

- Skill: `shanraisshan/draw-json-architecture` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add shanraisshan/draw-json-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shanraisshan/draw-json-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: shanraisshan (https://skillmd.com/u/shanraisshan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shanraisshan/draw-json-architecture

---


# Draw-JSON-architecture

One self-contained HTML Architecture Viewer per code flow, built from JSON in the surface's own folder. Walk the seven steps below **in order**, confirming with the user at each. **No file is written until step 7.** Long-form detail per step lives in `prompts/`.

## Step 1 — Read the flow

If `<flow>` is missing, stop with: `No flow provided. Re-run as /draw-json-architecture <flow>.` Otherwise echo it back and let the user correct the framing. → `prompts/01-read-flow.md`

## Step 2 — Name the surface

Derive a short kebab-case slug from the flow phrase — drop filler words, keep the meaningful nouns (`"home screen to order placement"` → `home-to-order`; `"user signup"` → `user-signup`). Confirm the folder it will create. → `prompts/02-name-the-surface.md`

## Step 3 — Research the repo, propose stops + lenses

Walk the journey in code, entry to exit. Propose **stops** (each "thing that happens": page, handler, job, redirect) and **lenses** (one per dimension you actually saw — ui, database, api, llm, or surface-specific: cache, queue, webhook, …). Cite the file for every lens. Confirm; loop until settled.

**Never propose a stop the code lacks. Never propose a lens you haven't seen.** → `prompts/03-research-the-flow.md`

## Step 4 — Pick a color per lens

For each confirmed lens, ask: *"What color should `<lens>` paint?"* Offer three CSS color names; user can override. Recap the palette and get one confirmation. → `prompts/04-pick-colors.md`

## Step 5 — Confirm evidence flags per lens

An evidence flag is any non-happy-path fact the diagram should expose. Classify each as `drift` (diagram/code disagreement), `risk` (real runtime or correctness hazard), or `assumption` (intentional modeling choice). For each lens, propose 2–4 candidates **from what you saw in step 3** — not a fixed list. User picks. → `prompts/05-confirm-drift.md`

## Step 6 — Pick lens + mechanism per stop

Before writing the graph, decide each stop's **primary lens** (`lens_selected`) and **call mechanism** (`type`) together. Mechanism is constrained by lens — e.g. `ui` only accepts `sequential` (a page render arrives sync); `api` accepts all four (`sequential`, `async`, `parallel`, `streaming`). Use `parallel` only for a proven fan-out; if serial code is modeled as structural fan-out, record that as an `assumption` in `reference.md`. Walk the user through every stop and confirm both fields in one pass. → `prompts/06-pick-mechanism.md`

## Step 7 — Author + build

Write source files under the configured source root (default `architecture/<slug>/`) using the lens+mechanism decided in step 6 (don't re-decide as you write), then run from the **repo root**:

1. `node skills/draw-json-architecture/scripts/validate.mjs <slug>` — structural check.
2. `node <sourceRoot>/<slug>/assets/<slug>.test.mjs` — surface truth-guard.
3. `node skills/draw-json-architecture/scripts/audit-claims.mjs <slug> --strict` — file/link/line/evidence/truth-guard audit.
4. `node skills/draw-json-architecture/scripts/coverage.mjs <slug> --model "<model>"` — coverage + meta-data refresh.
5. `node skills/draw-json-architecture/scripts/builder.mjs <slug>` — write the openable HTML.

Point the user at the builder output (default `architecture/<slug>/<slug>.html`). → `prompts/07-author-the-surface.md`

## Rules

- **Don't modify this skill's files** while drawing a surface — surface-specific data lives in the surface's folder.
- **Lens palette is per-surface.** Validator + coverage read each surface's palette from its `mapping.json`; new lenses need zero skill edits.
- **No hardcoded repo identity.** The GitHub link base is auto-derived from `git remote origin` and the repo's default branch (origin/HEAD, else the checked-out branch); missing remote → plain paths.
- **No unsupported claims.** Any `discrepancy.exist:true` entry must have code evidence, a category (`drift`, `risk`, or `assumption`), and a truth-guard assertion or an explicit reason why it cannot be guarded.

## Version

`version:` in this file's frontmatter is the only place the skill version is stored. Generated surfaces do not carry a skill version field.