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
Add ROADMAP.md for post-2.3.1 backlog
tt-a1icc893b135440
diff --git a/ROADMAP.md b/ROADMAP.mdnew file mode 100644index 00000000..8778dd2c--- /dev/null+++ b/ROADMAP.md@@ -0,0 +1,285 @@+# Archify Roadmap++Features planned but not yet shipped, in recommended implementation order.++Effort legend: **S** = afternoon · **M** = ~a day · **L** = multi-day.+Target versions are suggestions — bundle them however makes sense.++---++## 1. `?exportScale=N` URL parameter++**Effort:** S · **Target:** v2.4.0++### 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++**Effort:** S · **Target:** v2.4.0 (bundle with #1)++### What++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).++### Why++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.++### How++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:++```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 */+}+```++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;+}+```++**Consumer (hosted decoder page):**++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();`++Use `CompressionStream` / `DecompressionStream` (native, no pako dep needed — supported across Chrome 80+, Firefox 113+, Safari 16.4+).++### Tradeoffs++- **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=`.++### Done when++- "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.++### Open questions++- 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.++---++## 4. `diagram.yaml` intermediate format++**Effort:** L · **Target:** v3.0.0 (architectural break, worth its own major version)++### What++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.++### Why++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.++### 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.++---++## 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 (declined or deferred)++| 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. |