Stack Diagram vs Archify — complex-stack head-to-head
Date: 2026-11-20 · Run in: FINDS - TESTS (slate 3, test 5, at Ros's direction)
Subject (identical for both): Ros's Muse infrastructure, from the Archify v5 spec
~/workspace/design-skill-tests/archify-muse-setup.json (19 components, 25 connections, 3 cards)
Archify baseline: archify-muse-setup-v5.html (869,925 B interactive HTML, from the 8,574 B spec)
Stack Diagram outputs: this folder — muse-infra.html (source), out.html (built render),
muse-infra.png / muse-infra-dark.png, comparison screenshots at a shared viewport.
Smoke-test recap (2026-11-13, MY-VIZ)
Stack Diagram was first tried on the N-400 Practice app stack — a simple ~8-node system (Ros → Cloudflare Pages static app → KV behind Access, with Kokoro/GitHub tooling around it). It produced a self-contained HTML (111,415 B) plus light/dark PNGs, with a hand-placed layout and one fix loop, and worked as advertised. But that subject never stressed the tool: no fan-in/fan-out wider than 2, no grouping beyond one vendor box, no label load, and nothing to score fidelity against. This run was designed to answer what the smoke test couldn't — the same system Archify renders for the Muse Map re-audit, scored line-by-line against the Archify spec as ground truth.
Tool — provenance and upkeep
- Repo verified as find #72's: github.com/caru-ini/stack-diagram, cloned fresh for this
run; HEAD
5889b8edated 2026-11-19 (the day before the test). MIT license. - Created 2026-11-01 — 19 days old at test time — with 2,677 stars / 147 forks and 7 releases in 17 days (v0.3.0 Nov 2 → v0.7.0 Nov 18). Recent commits include merged outside PRs (#4, #6, #8, #9, #10: Databricks/Kubernetes/CNCF icon support, translations).
- Form: an agent skill (
skills/stack-diagram/— SKILL.md + geometry reference + template + three stdlib-only Python scripts), plus a public gallery site (stacks.caru.moe) insite/. - Upkeep verdict: extremely active, very young, effectively single-maintainer with growing contributor intake. Expect format churn at this cadence; the mitigation is structural — the skill is plain files, so the pinned clone used here keeps working whatever upstream does.
Method
Followed the skill's own workflow end to end:
- Content settled directly from the Archify spec (mapping below).
- Icons:
fetch_icons.py— 19/19 fetched first try. One real brand mark exists in this system (Claude, via devicon); every abstract node took a Lucide pictogram per the skill's rule ("abstract concepts get pictograms, not text"): workflow, database, clock, plug-zap, lock-keyhole, heart-pulse, wallet, briefcase, scale, code, book-open, house, brain, shield-check, app-window, library, file-text, user. - Layout: every coordinate pre-computed from
references/geometry.md(node = 132×~100 box, vertical edges box-bottom→tile-top, elbows in clear bands). Canvas widened from the template's 1000px to 1240×1060 to hold 8 departments at the mandated ≥140px pitch. Both 8-way fans use staggered bus levels (fan-out at y 460/472/484/496; fan-in at y 668/676/684/692) with fan-in entries staggered across the gate tile's top (x 594–648). - Build:
build.pyinlined icons + fonts →out.html. Zero unresolved tokens. - Verify:
render_png.py(Playwright, chromium headless shell 1255) at scale 2, light + dark, then full-res crops of the three riskiest junctions (Main Chat→Orchestrator, gate fan-in, fan-out/group label).
Iteration log
- Placement/fix iterations: 0. The first build passed the skill's own visual checklist — no arrow strikes text (the template's veil hides the one line that passes behind a wrapped role), no clipped nodes, group labels clear of edges, every icon visible in both themes. The pre-computation in step 3 is what bought this; the smoke test's one fix loop was on a far simpler diagram laid out less rigorously.
- The one visible compromise is not a placement error and can't be fixed by moving things: the 8 fan-in arrowheads compress into a tight comb on the Approval Gate's tile top, because entries already span the full 60px tile width (594–648). It's a format constraint (see scorecard), recorded rather than papered over.
- Environment setup (not diagram iterations): one venv +
pip install playwright(~3 min); the sandbox's existing chromium headless shell 1255 satisfied it — no browser download.
Fidelity scorecard vs the Archify v5 spec
| Spec element | Captured | Notes |
|---|---|---|
| Components | 19 / 19 | Every label exact; every sublabel carried verbatim (long ones wrap to two lines inside the 132px node box — text is complete, just wrapped) |
| Connections | 25 / 25 | Every endpoint pair correct; all 8 Orchestrator→dept and 8 dept→Gate edges drawn individually |
| Connection labels | 9 / 9 | All spec labels verbatim ("briefs · approvals" … "credentials stay in the vault"); the spec's 16 unlabeled connections are unlabeled here too |
| Edge variants | 2 / 3 | emphasis → accent ✓; dashed (crons) → dashed ✓; security (Orchestrator→Vault) → no equivalent class, rendered neutral solid |
| Cards | 0 / 3 as cards | No prose-card element exists. The Scale card's totals survive as the Departments group label ("36 teams · 85 jobs"); The Gate's content survives only as the gate's role line; "How work flows" is lost entirely |
| Node typing | 0 / 6 types | Archify types every node (frontend/backend/database/cloud/security/external) with a color + legend. Stack Diagram has no type system — groups are the only categorization |
| Invented content | None structural | Additions are presentational only: 2 group bands (Departments, Outputs), a legend, a lede. Accent is extended to Main→Orchestrator and Gate→outputs (Archify emphasises only Ros→Main Chat) — a disclosed style mapping so the primary path reads as one path, per the skill's own guidance |
What the tool structurally cannot express
- The gate as a control point. In Archify the gate is a 210×84 security-typed box with side anchors: 8 edges in, 3 out, spread across its perimeter — it reads as a funnel and carries visual rank. Here the gate is the same 60px tile as every other node; the funnel semantics survive (all department edges visibly converge before anything reaches the outputs group), but the gate has no visual rank, and the fan-in compresses into the arrowhead comb noted above. On this evidence, fan width ≥8 is where the fixed-tile format starts to strain.
- Cards / annotation layer. No equivalent of Archify's "How work flows" / "The gate" / "Scale" cards, and no node index (the Archify render lists all 19 nodes with sublabels).
- Interactivity. Static output: no search, route tracing, lens, zoom, or in-page theme
toggle (dark exists as the alternate PNG / a
data-themeattribute). Archify's render is an interactive page with all of those plus an Export menu. - Validation.
build.pyfails loudly on unresolved icon tokens, but nothing checks the diagram against the source data — a wrong team count would build happily. Same gap the D2 test found in D2; Archify's schema gates remain a real difference.
Output character and size
| Stack Diagram | Archify | |
|---|---|---|
| Source | 16,888 B hand-authored HTML (template + coordinates) | 8,574 B JSON spec (coordinates included) |
| Deliverable | 111,210 B self-contained HTML (fonts + icons inlined) | 869,925 B interactive HTML |
| Images | PNG pair at scale 2: 337,710 B light / 350,325 B dark | (export is a feature of the page itself) |
| Character | Static engineering drawing: graph paper, monochrome + one accent, logo/pictogram tiles, group bands. Prints and pastes anywhere | App-like page: color-typed nodes, cards, node index, ROUTE/LENS/search/zoom chrome |
| Themes | Light + dark from one source (attribute toggle) | Light + dark in-page toggle |
At ~7.8× smaller, the stack-diagram file is the one you'd paste into a wiki or a repo README; the Archify file is the one you'd present from.
Effort
- This run, wall clock ≈ 35 min total, of which: reading SKILL.md + geometry + template and the spec ≈ 10 min; environment setup ≈ 3 min; icon fetch ≈ 1 min; hand-authoring the HTML with pre-computed coordinates ≈ 8 min; build + render ≈ 1 min; visual verification (full renders + 3 crops, both themes) ≈ 5 min; comparison screenshots ≈ 2 min; the rest reporting. Fix iterations: 0 (see log).
- What the tool automates: icon sourcing/inlining, font embedding, theme tokens, arrowhead coloring (context-stroke), PNG rendering in both themes. What the author hand-places: everything else — every node coordinate, every edge path, every label position, all collision avoidance. There is no auto-layout and no auto-routing at all.
- Archify route, for comparison (per
~/workspace/finds-tests/d2-vs-archify-2026-11-19/report.md): the spec is an 8.4 KB JSON with hand-placedpos/sizeper component — the same hand-placement burden, paid in JSON instead of HTML — and the render then passed Archify's 4 validation gates and is deterministic. Archify's authoring cost is comparable; what the extra effort buys is validation, typing, cards, and interactivity. (The D2 report does not clock Archify authoring time; no number is claimed here.)
Verdict
Split by job — Archify keeps the Muse Map; Stack Diagram earns the static one-pager slot.
- For the Muse Map re-audit render (Ros's adopted standard): Archify stays. The cards, node typing, schema validation, interactivity, and the gate's visual rank are the product there, and stack-diagram can express none of them. Fidelity of the raw graph data, however, was perfect — 19/19 and 25/25 with every label — so this is a presentation-layer loss, not a comprehension loss.
- Where stack-diagram wins: quick, static, shareable architecture one-pagers — repo READMEs, wikis, blog posts, chat hand-overs — especially for brand-heavy stacks, where its real-logo fetching (this system has almost no brands, which played against it here) is the feature no other tested tool has. The light/dark PNG pair falls out of one build.
- Caution from this run: convergence-heavy topologies (fan-in/fan-out ≥ 8 into one node) stay legible but compress at the hub, because every node is the same 60px tile.
Test record (for Finds Library)
- Subject: Stack Diagram (github.com/caru-ini/stack-diagram, MIT, v0.7.0; repo created 2026-11-01, HEAD 2026-11-19) — find #72; alternative to Archify (find #64 lineage)
- Date: 2026-11-20
- What: rebuilt Ros's Muse infrastructure in stack-diagram from the exact Archify v5 spec (19 components, 25 connections, 3 cards), following the skill's own workflow — icon fetch, geometry-planned hand layout on a 1240×1060 canvas, build, render-and-inspect in both themes — and scored the result against the spec.
- Outcome: Success-with-caveats — graph fidelity perfect (19/19 components, 25/25
connections, 9/9 labels, all sublabels verbatim; nothing invented); zero fix iterations
after a fully pre-computed layout; output 111 KB static HTML + PNG pair vs Archify's
850 KB interactive page. Structural losses: 0/3 cards, no node typing, no interactivity,
no data validation,
securityedge variant inexpressible, and the Approval Gate loses its control-point rank (8-way fan-in compresses into a 60px tile top). - Output: this report +
muse-infra.html(source) +out.html(built) + light/dark PNGs + same-viewport comparison screenshots, in~/workspace/finds-tests/stack-diagram-2026-11-20/ - Reuse status: Reuse later — reach for stack-diagram on static, logo-forward stack one-pagers (READMEs, wikis, hand-overs); Archify remains the adopted standard for the Muse Map re-audit render.





