Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
Rewrite roadmap around Mermaid-aware v3.0
tt-a1i463cbe18ba81
diff --git a/README.md b/README.mdindex 2f4ee7e5..979a7162 100644--- a/README.md+++ b/README.md@@ -221,12 +221,11 @@ Archify 2.x 贡献:## 路线图-短期和长期计划见 [ROADMAP.md](ROADMAP.md):+详见 [ROADMAP.md](ROADMAP.md)。-- `?exportScale=N` URL 参数(恢复 1×/2× 轻量出图)-- 色盲友好调色板(Okabe-Ito)-- gzip+base64 分享链接-- `diagram.yaml` 中间格式(撬动 diff / auto-layout / Mermaid 导入 / C4 分层)+下一站是 **v3.0 — Mermaid-aware 架构**:把 Mermaid flowchart 当一等输入格式,Claude 继续主导布局判断,archify 负责渲染。简单说就是「把你 README 里的 mermaid 代码块粘进来 → 同样的图,但好看 10 倍」。中间夹一层极简 JSON IR (`diagram.json`),撬动 git diff、theme/palette 重渲染、CI 架构 diff bot 等附带能力。++> 经三轮独立评审,原 v2.4 / v2.5 计划(`?exportScale=N` URL 参数、色盲友好调色板、gzip+base64 分享链接、auto-layout)**全部砍掉**。每一项的理由记录在 ROADMAP 的「Not planned」段落里。## Licensediff --git a/ROADMAP.md b/ROADMAP.mdindex 8778dd2c..a163476a 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -1,285 +1,140 @@# Archify Roadmap-Features planned but not yet shipped, in recommended implementation order.+After v2.3.1 ships, the only remaining planned work is a Mermaid-aware v3.0. The original v2.4 / v2.5 backlog (export-scale URL param, color-blind palette, gzip+base64 share links) was considered and dropped — see [Not planned](#not-planned) for the rationale on each.-Effort legend: **S** = afternoon · **M** = ~a day · **L** = multi-day.-Target versions are suggestions — bundle them however makes sense.+This roadmap was rewritten on 2026-04-16 after three independent design reviews converged on the same architectural conclusions.----## 1. `?exportScale=N` URL parameter--**Effort:** S · **Target:** v2.4.0+## v3.0 — Mermaid-aware architecture### What-Re-expose 1× / 2× / 3× / 4× raster scale control — via URL parameter only, no UI selector. Default stays 4× for any user who doesn't care.--### Why--v2.3.0 removed the scale selector because "2× default + bitmap upsampling" produced soft output and the UI actively encouraged picking the softest option. The native-rasterization fix from 2.3 stays; this just restores an escape hatch for:--- Sharing compact PNGs in Slack / Notion / Discord where a 4000×2720 file is overkill-- Headless batch scripts wanting a specific output size-- Embedding in pipelines that re-compress anyway (no point in paying the 4× pixel cost upstream)--No UI surface means no regression back to the "soft by default" footgun.--### How--```js-function resolveRasterScale() {- try {- var v = parseInt(new URLSearchParams(location.search).get('exportScale'), 10);- if (v === 1 || v === 2 || v === 3 || v === 4) return v;- } catch (_) {}- return 4;-}-var RASTER_SCALE = resolveRasterScale();-```--Also:-- Let the existing canvas-size clamp (16 Mpx) continue to downshift automatically if `scale × viewBox` would exceed limits.-- Update the "Copied" toast to append `(Nx)` when `N !== 4`, so the user sees they got non-default output.-- Document in README's **URL parameters** section.--### Done when--- `?exportScale=2` produces a 2000×1360 PNG for the default viewBox.-- No parameter → output is byte-for-byte identical to v2.3.1.-- Canvas clamp still kicks in on oversized viewBoxes.-- README and CHANGELOG updated.-------## 2. Color-blind-safe palette+Introduce a thin JSON intermediate representation (`diagram.json`) that sits between input formats (Mermaid flowchart, Claude-written IR) and the existing HTML template. **Mermaid is a first-class input format; auto-layout is explicitly out of scope.** Claude does the layout work, just like today — only now it can ingest a Mermaid diagram as a starting point instead of starting from a chat description.-**Effort:** S · **Target:** v2.4.0 (bundle with #1)--### What+### Why this shape (and not the original "diagram.yaml" plan)-A third CSS-variable set `[data-palette="cb"]` orthogonal to the existing `[data-theme]` axis. Uses the Okabe-Ito palette (seven colors designed to be distinguishable under deuteranopia, protanopia, and tritanopia).+Three independent reviews converged on:-### Why+1. **Auto-layout (dagre / elk-js) is a dead end for archify.** The aesthetic — Auth Provider floating outside the AWS region, S3 deliberately below CloudFront to imply a serving relationship, security-group boundary at exact 30/50 padding, summary cards, legend nested into dead space — *is* the layout decisions. Stripping the human (or Claude) out of layout strips the product of its differentiator. Dagre output of a typical 8-node graph is a uniform rectangular grid; CSS-skinning it gets you only ~30% of the way from "stock Mermaid" to "archify hand-placed."-Archify's default palette uses emerald (backend) + rose (security) + violet (database) — emerald and rose are hard to distinguish under red-green deficiency, which affects ~8% of males. For inclusive team docs, architecture reviews, and conference slides, an accessible option matters.+2. **"Prettier Mermaid renderer" is already taken.** [lukilabs/beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) ships 15 themes (Tokyo Night, Catppuccin, Nord, Dracula…) with 8.1k stars and is growing fast. Mermaid 11.14 itself added Neo / Redux themes + ELK layout + Hand Drawn look. Competing as "the prettier Mermaid library" is uphill. Archify's real moat is *information architecture* (semantic colors per technology, security boundaries, summary cards, deliberate spatial narrative), not just "prettier CSS on top of Mermaid".-### How+3. **JSON beats YAML as the IR format.** LLM-generated YAML has a high "looks right, parses wrong" failure rate due to whitespace sensitivity, and the inline-flow `pos: [40, 80]` / `sublabel: "Redis :6379"` patterns hit YAML quoting gotchas. JSON has unambiguous parsing, native browser `JSON.parse`, mature JSON Schema validation, and is human-readable enough for `git diff`.-Add a palette axis alongside the theme axis. Existing CSS structure already has every color as a variable, so this is just one more block:+### Architecture-```css-[data-palette="cb"] {- --frontend-stroke: #56B4E9; /* sky blue */- --backend-stroke: #009E73; /* bluish green */- --database-stroke: #CC79A7; /* reddish purple */- --cloud-stroke: #E69F00; /* orange */- --security-stroke: #D55E00; /* vermillion */- --messagebus-stroke: #F0E442; /* yellow */- --external-stroke: #0072B2; /* blue */- /* matching rgba fills for each */-}+```+ ┌→ Mermaid output (P4, v3.1+)+ │+ Mermaid input ─┐ │+ ├→ IR (JSON) ─→ Claude ────┼→ archify HTML+ Claude direct ─┘ fills │+ coords └→ PNG / JPEG / WebP / SVG+ + classes```-Toggle surfaces:-- URL parameter `?palette=cb` (mirrors the existing `?theme=` pattern).-- Optionally: an accessibility button in the toolbar next to the theme toggle. Button label can be a small `◐` glyph with `aria-label="Color palette"`.--Persistence: `localStorage['archify-palette']`, URL param wins.--### Done when--- Dark + default, Dark + cb, Light + default, Light + cb all render cleanly.-- URL override works alongside localStorage persistence.-- README documents `?palette=cb`.-- SKILL.md notes that palette is orthogonal to theme.-- Legend + summary-card dots re-map correctly under the cb palette.-------## 3. gzip + base64 share links--**Effort:** M · **Target:** v2.5.0--### What--"Share" button in the toolbar that compresses the entire generated HTML into the URL fragment, producing a self-contained link. Opening the link reconstitutes the diagram in-browser. No server, no attachment.--### Why--Today, sharing a diagram means attaching an HTML file. A URL is strictly better for:-- Slack / Discord / Teams (shows as link unfurl inline)-- GitHub / GitLab issue + PR comments-- Jira / Linear / Notion pages-- Email + RFC drafts-- Browser bookmarks + history--### How--Two halves:--**Producer (in the generated HTML):**--```js-async function createShareLink() {- const html = '<!DOCTYPE html>\n' + document.documentElement.outerHTML;- const stream = new Blob([html]).stream().pipeThrough(new CompressionStream('gzip'));- const bytes = new Uint8Array(await new Response(stream).arrayBuffer());- const b64 = btoa(String.fromCharCode.apply(null, bytes));- return SHARE_BASE_URL + '#data=' + b64;+The "Claude in the loop" property is the moat, not a limitation. Auto-layout libraries see edges and nodes; Claude sees architectural meaning and lays out accordingly.++### IR (`diagram.json`) — minimal v1 schema++```json+{+ "schema_version": 1,+ "meta": {+ "title": "agmon",+ "subtitle": "AI agent observability",+ "theme": "dark",+ "viewBox": [1000, 680]+ },+ "components": {+ "claude_code": {+ "type": "external",+ "label": "Claude Code",+ "sublabel": "AI coding agent",+ "pos": [40, 80],+ "size": [140, 60]+ }+ },+ "connections": [+ {+ "from": "claude_code",+ "to": "agmon_emit",+ "label": "hooks (stdin)",+ "variant": "default"+ }+ ]}```-**Consumer (hosted decoder page):**+**Deliberately out of v1:** security-group boundaries, region boundaries, summary cards, footer, palette toggle. These stay in the HTML template where they live today. The IR is only for the SVG component graph — the part that needs to round-trip through Mermaid.-A static page at `archify.pages.dev/` (Cloudflare Pages, free tier) that:-1. Reads `location.hash`-2. Base64-decodes, runs it through `DecompressionStream('gzip')`-3. `document.open(); document.write(html); document.close();`+`schema_version: 1` is mandatory from day 1. Validated via JSON Schema. All fields except `schema_version` and the component `type` are optional with documented defaults.-Use `CompressionStream` / `DecompressionStream` (native, no pako dep needed — supported across Chrome 80+, Firefox 113+, Safari 16.4+).+### Phasing-### Tradeoffs+| Phase | Deliverable | Target |+|---|---|---|+| **Validate** | 5-Mermaid blind-rate experiment. Continue only if it passes. | (no version) |+| **P0** | JSON IR + JSON Schema validator + `schema_version` enforcement | v3.0-alpha |+| **P0.5** | `render.js` — pure-JS renderer takes IR → HTML using existing template. Coordinates required (no auto-layout in the renderer). | v3.0-alpha |+| **P1** | Mermaid flowchart parser → IR (extracts nodes, edges, `subgraph` blocks, `:::class` hints; leaves `pos` empty) | v3.0-beta |+| **P2** | Updated SKILL.md teaching Claude to read Mermaid-derived IR, fill positions with archify spatial reasoning, apply semantic classes | v3.0-beta |+| **P3** | End-to-end pipeline + re-run validation experiment on real output | v3.0 |+| **P4** | IR → Mermaid output (round-trip) + C4 DSL input adapter | v3.1+ |-- **URL length:** Chrome handles ~32 KB fragments reliably. A typical archify diagram compresses to 5–15 KB. Very large diagrams (30+ components) may bump into the limit — fall back to a "Diagram too large to share as link" message with a download button.-- **Security:** The decoder `document.write()`s arbitrary HTML. The decoder page must live on a dedicated hostname that never holds user credentials, so XSS-via-share-link can't exfiltrate anything interesting. Never run the decoder on the same origin as an account system.-- **Fragment vs query param:** `#data=` stays client-side (never hits server logs). Prefer it over `?data=`.+### Validation experiment (mandatory before P0)-### Done when+The whole v3.0 bet rests on: "Mermaid input + Claude layout + archify CSS" looks noticeably better than stock Mermaid. If it doesn't, the architecture has no point.-- "Share" button produces a URL < 30 KB for a typical 8-component diagram.-- Opening the link in a fresh tab reconstitutes the exact same page (theme, palette, everything).-- Link works after pasting into Slack / GitHub (tested in a throwaway thread).-- Decoder page is deployed and versioned (e.g., `archify.pages.dev/v1/`).-- Fallback flow triggers cleanly when payload exceeds the threshold.+**Procedure.** Pick 5 real Mermaid flowcharts:-### Open questions+1. Mermaid docs' canonical flowchart example+2. Kubernetes deployment diagram from a popular README+3. Microservices diagram from `awesome-architecture` or similar+4. CI/CD pipeline (GitHub Actions / GitLab style)+5. Simple 3-tier web app-- Should the decoder sanitize anything? The HTML is self-written by Archify, but a malicious actor could craft a payload. Mitigation: only run decoder on dedicated hostname, set strict CSP on the decoder page.-- Versioning: if the template changes, do older share links still work? Yes — the link contains the entire old template inline, so it's self-contained. Decoder just `document.write()`s whatever's in the blob.+For each, produce three versions:----+- **(A)** Stock Mermaid via `mmdc` default theme+- **(B)** Mermaid + archify-style `themeCSS` injection — mimics the v3.0 path *before* any Claude polish (proxies "auto-layout + nice CSS, no spatial reasoning")+- **(C)** Hand-placed in archify HTML by Claude — proxies the v3.0 path *after* Claude polish-## 4. `diagram.yaml` intermediate format--**Effort:** L · **Target:** v3.0.0 (architectural break, worth its own major version)--### What+Show all 15 screenshots, unlabeled and randomized, to 5 engineers outside the project. Ask:-Claude writes a structured YAML spec describing the diagram (components, connections, groups, positions, metadata) instead of one-shot HTML. A renderer (JS module) turns the YAML into the existing HTML template.+- Rate each diagram 1–10 for visual quality+- For each diagram (groups of 3), pick which version you'd want in your README-### Why+**Pass criterion:** B averages ≥ 7/10 **and** is rated closer to C than to A in at least 4 of the 5 diagrams.-Today, every iteration ("move Redis to the left") triggers Claude to regenerate the entire HTML, which frequently shifts unrelated coordinates. A structured intermediate format unlocks:--| Capability | How it uses the YAML |-|---|---|-| Stable iterative edits | Modify one field; renderer preserves everything else |-| Version diffing | `git diff` on YAML is human-readable |-| Theme / palette re-render | One YAML × N themes = N HTMLs without re-prompting Claude |-| Mermaid / PlantUML import | Parser: source → YAML → HTML |-| Auto-layout via Dagre / ELK | Read YAML, recompute `pos`, re-render |-| C4 layer navigation | Add `layer: context / container / component` field |-| CI architecture diff bot | PR bot renders before.yaml vs after.yaml side-by-side as PNGs |--### Schema sketch--```yaml-meta:- title: agmon- subtitle: AI agent observability- theme: dark # dark | light- palette: default # default | cb- viewBox: [1000, 680]--components:- claude_code:- type: external # frontend | backend | database | cloud | security | messagebus | external- label: Claude Code- sublabel: AI coding agent- pos: [40, 80]- size: [140, 60]-- agmon_emit:- type: backend- label: agmon emit- sublabel: hook stdin bridge- pos: [410, 80]- size: [150, 60]--connections:- - from: claude_code- to: agmon_emit- label: "hooks (stdin)"- variant: default # default | emphasis | security | dashed--groups:- - type: security-group- label: "sg-name :port"- contains: [load_balancer]--cards:- - title: Security- color: rose- items:- - OAuth 2.0 via external provider- - TLS everywhere--footer: "T toggle theme · E open Export"-```--### How (phased)--**Phase A — Renderer only (no LLM changes).** `render.js` (plain JS, runs in browser or Node) reads a YAML file → outputs the existing HTML. Power users can hand-write YAML. Ships as a library + CLI; template still works standalone. Target: v2.6.--**Phase B — SKILL.md rewrite.** Claude produces YAML + a one-line "render this" note first, and the HTML second. Users iterate by asking Claude to modify the YAML; the renderer regenerates the HTML. Target: v3.0.--**Phase C (optional) — Expose the renderer as:**-- CLI: `npx archify render diagram.yaml > diagram.html`-- Cloudflare Worker: POST YAML → HTML-- VS Code extension: side-by-side YAML → preview--### Tradeoffs--- **Pro:** Unlocks diffing, auto-layout, Mermaid import, C4 layers, CI integration — every backlog feature becomes easier.-- **Pro:** Claude output becomes more deterministic and reviewable.-- **Con:** Two artifacts per generation (YAML + HTML) is slightly more complex for first-time users. Mitigate by generating HTML inline in the chat as usual; the YAML is an artifact, not a required read.-- **Con:** Breaks the "generate → open → done" single-artifact promise — there's now a source-of-truth question. We'd need to be clear the YAML is canonical and the HTML is regenerable.-- **Con:** Renderer becomes the canonical implementation path. The current template.html stays, but it becomes a target rather than the source.+**Fail action:** Kill the Mermaid-input-as-headline path. v3.0 collapses to "Claude-native JSON IR for stable iteration" only; Mermaid input becomes a SKILL.md prompt-engineering trick instead of a real parser. P1/P2/P3/P4 all rescoped or dropped.### Done when-- `render.js` can reproduce today's `examples/web-app.html` from a hand-written YAML.-- YAML schema documented in `docs/yaml-schema.md`.-- Claude, prompted via the updated SKILL.md, produces valid YAML that renders correctly.-- Re-theming (dark → light, default → cb palette) is a YAML edit + re-render, no re-prompt.-- `git diff` between two diagram YAMLs is actually readable.-- Backward-compat: hand-written or 2.x-generated HTML still works in a browser; it's just no longer the primary output format.+- `render.js` reproduces today's `examples/web-app.html` byte-for-byte from a hand-written `diagram.json`.+- The Mermaid flowchart parser successfully ingests the 5 validation diagrams.+- Claude, given a positionless parsed IR, produces HTML that meets the success criterion above on at least 4 of 5 diagrams.+- `schema_version: 1` is documented in `docs/diagram-json-schema.md` with the full JSON Schema published.+- Round-trip works: `mermaid → IR → Claude (fills positions) → HTML` and `Claude → IR → render.js → HTML` are both supported flows.+- README and SKILL.md updated to describe the new input pipeline.----## Recommended order--1. **`?exportScale=N`** (S) — fills a gap left by v2.3 at near-zero effort.-2. **Color-blind palette** (S) — CSS-variable system is already in place; high ratio of user impact to effort.-3. **gzip + base64 share** (M) — meaningful UX win for every sharing interaction.-4. **`diagram.yaml`** (L) — architectural; bundle under v3.0.--Features 1 and 2 are good candidates to ship together as v2.4.0.-Feature 3 is v2.5.0.-Feature 4 is v3.0.0.-----+## Not planned-## Not planned (declined or deferred)+Each item below was considered and explicitly declined. Listed so issue submitters can find prior decision context.| Idea | Why not ||---|---|-| Zoom & pan | Browser native pinch / Cmd-scroll already works; minimal gain for significant code. |-| Auto-layout (Dagre / ELK) | Conflicts with hand-placed aesthetic; blocked on `diagram.yaml`. |-| Annotation / overlay mode | Pushes toward an editor, not a viewer. |-| C4 layer tabs | Blocked on `diagram.yaml`. |-| Diagram diff UI | Better as a companion CLI than template bloat. |-| Mermaid import | Can be addressed via SKILL.md prompt engineering first; full parser after `diagram.yaml`. |-| PDF export button | `Cmd+P → Save as PDF` already works, print stylesheet handles the rest. |-| Font-embedding in exports | `local()` fallback (2.2) covers the common case; full embed would add ~150 KB per generated file. |+| **`?exportScale=N` URL parameter** | v2.3 explicitly removed the scale selector because it encouraged users to pick a soft output. Re-adding it — even as URL-only with no UI — is a back door to the same footgun. Users needing smaller raster files can resize externally. |+| **Color-blind-safe palette (Okabe-Ito)** | Maintenance burden — every new component class needs a CB variant — outweighs adoption. The CSS-variable system means downstream forks can roll their own palette in ~30 lines without an upstream change. |+| **gzip+base64 share links** | Requires a long-running hosted decoder page, opens an XSS-via-share-link vector that's hard to fully close even with a separate hostname, and bumps URL length limits on realistic diagrams. The "send a single HTML file" workflow is already friction-free. |+| **Auto-layout (dagre / elk-js)** | Independently flagged by all three v3.0 design reviews as the primary risk to archify's aesthetic. The hand-placed coordinate system *is* the product; automating it is automating away the differentiator. |+| **YAML as the IR format** | LLM-generated YAML has a high "looks right, parses wrong" failure rate due to whitespace sensitivity. JSON is unambiguous, has native browser support, and is sufficient for `git diff` readability. |+| **General-purpose graph IR adoption** (Cytoscape JSON / GraphViz DOT / GraphML / Mermaid AST / D2 / C4 DSL) | Each evaluated against archify's actual requirement: hybrid of graph topology + visual layout + non-graph metadata (cards, footer, region boundaries). None covers all three cleanly; the wrappers needed amount to inventing a custom schema anyway. |+| **Zoom & pan UI** | Browser native pinch / Cmd+scroll already works on the SVG. Minimal gain for significant added code. |+| **Annotation / overlay editor mode** | Pushes archify toward being an editor. Positioning is *generator + viewer*, not editor. |+| **Diagram diff UI** | Better delivered as a companion CLI / CI bot than baked into the template. Blocked on `diagram.json` shipping anyway. |+| **PDF export button** | `Cmd+P → Save as PDF` already produces clean output via the v2.2 print stylesheet. No need for a dedicated button. |+| **Font embedding in raster exports** | `local()` fallback (v2.2) covers the common case (developers with JetBrains Mono installed). Full embed adds ~150 KB to every generated HTML file for marginal benefit. |