Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Rewrite roadmap around Mermaid-aware v3.0

tt-a1i463cbe18ba81
diff --git a/README.md b/README.md
index 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」段落里。
## License
diff --git a/ROADMAP.md b/ROADMAP.md
index 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 &middot; **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. |