animated-architecture-diagram

name

animated-architecture-diagram

description

Generate a self-contained HTML architecture diagram in the HuggingFace research-article style: D3-driven flow-dot animation along edges, hover-to-trace + tooltips, data(solid)/event(dashed) dual-channel edges, light/dark theme, a11y (aria + prefers-reduced-motion + replay + scroll-autoplay). The model authors a JSON spec (nodes/edges/seq); a committed renderer owns the D3/CSS. Use when the user wants an ANIMATED or interactive architecture/pipeline/data-flow diagram, a "gif-like" flowing-data figure, an HF/distill-style embed, "애니메이션 아키텍처 다이어그램", "데이터 흐름 애니메이션", "인터랙티브 도식", "허깅페이스 스타일 도식", "블로그용 아키텍처 gif". Do NOT use for a static diagram (use architecture-diagram), Mermaid rendering (use mermaid-render), or a rendered MP4 motion-graphics video (use manim-video / hyperframes / remotion-motion-forge). For a simple flowchart use flowchart.

Animated Architecture Diagram (HuggingFace-style D3 embed)

Reproduces the HuggingFace realtime-voice blog figure style: labeled boxes, a forward data cascade with flow dots animating along the arrows, a dashed event side-channel flowing back, hover-to-trace highlighting with tooltips, light/dark theming, and accessibility. Output is one self-contained .html that opens in any browser and autoplays on scroll-into-view (looks like a GIF, but stays crisp and interactive). Optionally capture to PNG/MP4/GIF for slides.

Format determinism ([[sonnet-format-determinism]]): the D3 machinery + CSS live in the committed assets/template.html. You author only the JSON spec (the content). Never hand-write the D3/SVG — fill the model and run the renderer.

Workflow

Two ways to get a spec — auto (default) or hand-authored.

Path A — convert an existing Mermaid flow (DEFAULT, no hand-placing). Most flows (incl. every flowchart/graph in a blog post) convert automatically. The bridge parses the Mermaid and computes coordinates with dagre:

node scripts/mermaid_to_spec.mjs block.mmd --out spec.json --title "..."
# or pipe a whole .md (first ```mermaid block is used):
cat post.md | node scripts/mermaid_to_spec.mjs - --out spec.json

It handles node shapes ([] () {} ([]) (()) {{}}), edges (--> --- -.-> ==> with |labels| or -- mid -- labels), subgraphs→groups, -.->→event(dashed), TD/LR direction, <br/> multi-line. Unparseable lines are WARNED, not dropped. Then go to step 2. Hand-tune the emitted spec only if a dense graph needs it. (Requires @dagrejs/dagre — npm i once in this skill dir.)

Path B — author a spec by hand (new diagram, or full control): Write the JSON spec: nodes[] (id, x, y, w, h, title, sub, desc), edges[] (src, dst, kind, line|curve, label), optional groups[] and seq[]. Read references/spec-schema.md for the schema + coordinate recipe. Start from examples/metis-realtime.json — tuned, reusable for any left→right cascade.

1. Get a spec via Path A (auto) or Path B (hand).
2. Render + gate:

   python3 scripts/render.py <spec.json> --out <out.html> --title "..." \
     --screenshot <out.png>          # static frame proof (headless Chrome)
   

   The renderer validates (unique node ids, every edge endpoint is a real node, every edge has line|curve, seq indices in range) and exits 1 on failure — fix the spec, do not patch the HTML.
3. Verify ([[evaluator-must-act]]): Read the PNG. Confirm no overlapping boxes, arrows land on box edges (not centers), labels don't collide, and a flow dot is visible. Regenerate the spec if not.
4. Show it ([[display-generated-images]]): in an interactive session, add --open to pop the live animated .html. (Skip --open in headless/cron.)

Authoring the model (the only thing you write)

• Coordinates are manual (like the HF original) — full control, no layout engine. Lay a left→right cascade on a ~960×384 canvas: a top "server/adapter" row and a bottom "pipeline" row, wrapped in dashed groups. Reuse the example's numbers and just relabel for a same-shaped system.
• Edge kinds carry meaning: "kind":"data" = solid primary (forward payload); "kind":"event" = dashed muted (side-channel / callbacks flowing back). Use both to get the signature two-layer look.
• Straight vs curved: line:[x1,y1,x2,y2] for adjacent hops; curve:[[p0],[p1],[p2],[p3]] (cubic Bézier) for the long returns to the top row. Curved edges take off:"50%" to place the label along the path.
• Flow sequence (seq): list { "e": <edgeIndex>, "t0": <ms> } to choreograph one turn through the cascade (event dispatches overlap the next data hop, like the real pipeline). Omit seq → the renderer auto-plays the data edges forward.
• desc on each node → hover tooltip. Keep it one honest sentence; do not invent components the user didn't describe ([[critical-thinking]]).

Optional: capture to MP4 / GIF / frames (for slides / blog / Slack)

The .html is the primary deliverable. For a shareable clip of the animation:

node scripts/capture.mjs <out.html> --mp4 <out.mp4>     # or --gif / --frames <dir>

Requires playwright (npm i playwright && npx playwright install chromium). Graceful: if playwright is missing it prints install steps and exits — the .html still works. render.py --screenshot (headless Chrome, always available on this Mac) gives a static frame with zero extra deps.

Files

• assets/template.html — committed D3 harness (format owner). Do not edit per-diagram.
• scripts/mermaid_to_spec.mjs — Path A: Mermaid flowchart/graph → spec.json (dagre auto-layout). Requires @dagrejs/dagre.
• scripts/render.py — spec.json → standalone .html (--embed fragment for blogs, validate gate, --screenshot, --open, --id). Stdlib only. Multi-instance safe.
• scripts/convert_posts.py — batch triage + in-place convert of Mermaid flows in Jekyll posts. TRIAGE (default, read-only): classify every ```mermaid block by type + node-count. APPLY (--apply, --max-nodes N, --dry-run): replace convertible flow blocks with {% raw %}-wrapped embeds; skips non-flow / dense / bridge-warned blocks. Working-tree only (reversible).
• scripts/capture.mjs — optional playwright capture to mp4/gif/png frames.
• references/spec-schema.md — full field schema + coordinate authoring recipe.
• examples/metis-realtime.json — tuned reference spec (ThakiCloud Metis voice cascade).

Gotchas

• D3 v7 loads from jsDelivr CDN at view time (keeps the file small). Offline viewers need network on first load; for a truly offline file, inline d3.min.js into the template.
• Coordinates are the whole game — if boxes overlap or arrows miss, adjust x/y/w/h in the spec and re-render; never nudge the generated SVG by hand (next render overwrites).
• This is for quality reader-facing diagrams. For a throwaway internal sketch, a static architecture-diagram or mermaid-render is cheaper ([[token-diet-hygiene]]).
• Lineage: distilled from HuggingFaceM4/hugging-voice d3-realtime-architecture.html (same interaction/animation/a11y patterns, generalized to a JSON-spec renderer).