Skip to content
Back to search

fireworks-tech-graph

Create precise SVG technical diagrams, export PNG or offline HTML, and animate supported semantic SVGs to GIF. Use for architecture, UML, agent, cloud or workflow diagrams; not photos, raster art or statistical charts.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yizhiyanhua-ai-fireworks-tech-graph/badge.svg)](/listings/yizhiyanhua-ai-fireworks-tech-graph)

HTML

<a href="/listings/yizhiyanhua-ai-fireworks-tech-graph"><img src="/api/listings/yizhiyanhua-ai-fireworks-tech-graph/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Recommended: install the complete skill for both runtimes

Use the real nested skill path. The final `/skills/fireworks-tech-graph` segment is required because a bare repository install can select only the root `SKILL.md` in current versions of `skills` CLI.

npx -y skills@1.5.17 add \
  yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph \
  --agent codex claude-code -g -y --copy

This creates complete copies at `~/.agents/skills/fireworks-tech-graph` for Codex and `~/.claude/skills/fireworks-tech-graph` for Claude Code, including scripts, schemas, fixtures, templates, tests, references, and metadata.

Editable Git checkout for Codex

mkdir -p ~/.agents/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.agents/skills/fireworks-tech-graph

Codex discovers personal skills from `~/.agents/skills` and reads the optional `agents/openai.yaml` metadata included in this repository.

Editable Git checkout for Claude Code

mkdir -p ~/.claude/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.claude/skills/fireworks-tech-graph

Claude Code discovers personal skills from `~/.claude/skills` and ignores the Codex-only UI metadata.

One editable checkout shared by Codex and Claude Code

For a fresh install with Claude Code 2.1.203 or newer, keep one checkout and link both discovery paths to it. Move any existing destinations aside before creating the links.

mkdir -p ~/.local/share/agent-skills ~/.agents/skills ~/.claude/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.local/share/agent-skills/fireworks-tech-graph
ln -s ~/.local/share/agent-skills/fireworks-tech-graph ~/.agents/skills/fireworks-tech-graph
ln -s ~/.local/share/agent-skills/fireworks-tech-graph ~/.claude/skills/fireworks-tech-graph

This keeps `SKILL.md`, references, scripts, templates, and future updates identical in both agents. The npm registry is a separate distribution channel and may lag GitHub Releases. For the current Skill version, use the nested GitHub path above; the npm page remains available for package metadata:

https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 99 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: fireworks-tech-graph
  3. description: >-
  4. Create precise SVG technical diagrams, export PNG or offline HTML, and animate
  5. supported semantic SVGs to GIF. Use for architecture, UML, agent, cloud or
  6. workflow diagrams; not photos, raster art or statistical charts.
  7. ---
  8. # Fireworks Tech Graph
  9. One portable Agent Skill for Codex and Claude Code. SVG is the canonical artifact;
  10. PNG, offline HTML and supported GIF motion are output routes. Preserve requested
  11. labels, topology and meaning; a successful command is not a visual quality verdict.
  12. ## Locate and select
  13. Resolve the directory containing this file as `SKILL_ROOT`. Use
  14. `${CLAUDE_SKILL_DIR}` in Claude Code or the absolute directory in Codex's loaded
  15. skill metadata. Do not assume cwd or a previous shell variable persists.
  16. Use the installed version for the task. Run `version` for source/version questions
  17. and `doctor` when diagnosing a missing renderer, font or dependency; do not make
  18. installation, updates or a complete test suite prerequisites for every diagram.
  19. ```bash
  20. SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-codex-skill-metadata}"
  21. python3 "$SKILL_ROOT/scripts/fireworks.py" version
  22. ```
  23. - Honor the user's diagram type, content and style; choose sensible reversible
  24. details from the brief. Ask only for a material missing engineering fact or
  25. a choice the user explicitly reserved. A request to draw includes local rendering.
  26. - Styles 1–7 and 9–12 have JSON generators. Style 8 (Dark Luxury) remains
  27. AI-authored SVG: use its style reference, then the same validation/export gates.
  28. - Default to Style 1 Flat Icon when no user/workspace preference applies. Load the
  29. actual matching file from [the style matrix](references/style-diagram-matrix.md).
  30. Read other styles only for a requested comparison.
  31. - Styles 9–12 default to C4, cloud, event and observability semantic contracts.
  32. Validate facts before layout; do not invent responsibilities, protocols or metrics.
  33. - Adapt an existing valid SVG directly when appropriate. JSON generation is not
  34. required for every edit. Use [diagram/layout guidance](references/diagram-layout-reference.md)
  35. and [icons](references/icons.md) only for the relevant type or symbols.
  36. ## Generate and check
  37. Reuse the user's current brief and artifact; an extra planning document is optional.
  38. For JSON work, select `text_policy: "strict"` when all labels must be visible exactly.
  39. The compatible `report` default preserves full labels in SVG metadata and reports
  40. any visible truncation. Resolve that warning before claiming complete exact text.
  41. For polished work apply the [composition contract](references/composition-quality-contract.md).
  42. ```bash
  43. SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-codex-skill-metadata}"
  44. python3 "$SKILL_ROOT/scripts/fireworks.py" validate architecture input.json
  45. python3 "$SKILL_ROOT/scripts/fireworks.py" render architecture input.json diagram.svg --report layout.json
  46. python3 "$SKILL_ROOT/scripts/fireworks.py" check diagram.svg
  47. python3 "$SKILL_ROOT/scripts/fireworks.py" export-png diagram.svg diagram.png --width 1920
  48. ```
  49. `check` validates SVG identity, marker references, generic collisions, semantic
  50. geometry and composition. Inspect the report's typography and palette scope;
  51. heuristic text widths do not replace inspecting the actual rendered font.
  52. Use [visual quality guidance](references/visual-quality.md) for readability and
  53. style-specific refinements. Keep one semantic connector per business edge.
  54. ## Additional outputs
  55. - **PNG:** prefer `export-png`, which reads root canvas dimensions, limits output
  56. size, writes atomically and reads the PNG dimensions back. Alternate renderer
  57. details are in [PNG export](references/png-export.md).
  58. - **HTML:** `fireworks.py export-html diagram.svg diagram.html`. One sanitized
  59. offline file provides pan/zoom, source copy and static image downloads.
  60. - **GIF:** “Generate a GIF”, “Animate this diagram”, “生成 GIF”, “制作 GIF” and
  61. “让这张图动起来” select the existing semantic SVG's motion route. Styles 1–12 are enabled
  62. for the documented scene contracts; arbitrary same-style topologies are not
  63. promised. Load [motion effects](references/motion-effects.md) and run
  64. `fireworks.py animate diagram.svg diagram.gif`. Default is 960px, 20fps, 5.75s
  65. with the `+2s-settled-flow` preset and a `.motion.json` report. Historical
  66. `user-approved` fields describe maintainer-reviewed presets, not authorization
  67. from the current user to publish, spend or send data.
  68. ## Verify the requested outcome
  69. Inspect the final PNG at intended reading size when image viewing is available:
  70. check text completeness, contrast, font substitution, hierarchy, spacing, clipping,
  71. arrow direction, crossings and labels. Preserve style palette and material while
  72. fixing defects. Reuse an unchanged reviewed render; do not keep adding tests or
  73. polish after acceptance passes. If viewing is unavailable, explicitly mark the
  74. visual check skipped and do not claim visual correctness.
  75. After a failed check, use its element IDs and geometry to make a focused repair;
  76. change the approach after two unchanged failures. Widen/split an overfull diagram
  77. instead of hiding required copy or endlessly shrinking type. Do not silently
  78. weaken semantic or composition constraints to obtain a pass.
  79. Complete every requested local output and its applicable checks, then report file
  80. paths, dimensions, visual review and residual limitations. A first SVG does not
  81. complete a requested PNG/GIF/HTML package. Publication or remote delivery requires
  82. its own scope-matching authorization; existing authorization is not requested twice.
README.md · README · 745 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [English](README.md) | [中文](README.zh.md)
  2. [Release history](docs/releases/README.md) · [Changelog](CHANGELOG.md)
  3. # fireworks-tech-graph
  4. > **Stop drawing diagrams by hand.** Describe your system in English or Chinese — get geometry-safe SVG, PNG, focused SVG-to-GIF motion, and offline interactive technical diagrams.
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  6. [![GitHub Release](https://img.shields.io/github/v/release/yizhiyanhua-ai/fireworks-tech-graph)](https://github.com/yizhiyanhua-ai/fireworks-tech-graph/releases)
  7. [![Codex Skill](https://img.shields.io/badge/Codex-Skill-10a37f)](https://learn.chatgpt.com/docs/build-skills)
  8. [![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-d97757)](https://code.claude.com/docs/en/skills)
  9. [![12 Visual Styles](https://img.shields.io/badge/Styles-12-purple)]()
  10. [![14 Diagram Types](https://img.shields.io/badge/Diagram%20Types-14-green)]()
  11. [![UML Support](https://img.shields.io/badge/UML-Full%20Support-orange)]()
  12. ---
  13. ## Output quality
  14. The current checkout adds complete-text reporting and stronger supporting text across the default themes. Add `"text_policy": "strict"` to reject visible truncation before output is written; reports preserve the full source label and explain how to recover. Chinese descriptions use the available second line. See [visual quality](references/visual-quality.md) for theme-specific guidance and measurement limits.
  15. ```bash
  16. python3 "$SKILL_ROOT/scripts/fireworks.py" version
  17. python3 "$SKILL_ROOT/scripts/fireworks.py" export-png diagram.svg diagram.png --width 1920
  18. ```
  19. `version` reports the package, actual Skill root and Git state when available. `doctor` distinguishes SVG/HTML support from optional PNG/GIF dependencies. PNG export checks the root canvas, bounds image size, writes atomically and reads the resulting pixel dimensions back. The browser PNG exporter remains available for Chromium fidelity. The showcase GIFs below are the published 1.2.0 references; this unreleased upgrade preserves their motion contracts.
  20. ## Overview
  21. `fireworks-tech-graph` is one Agent Skill that works unchanged in **Codex and Claude Code**. It turns natural language descriptions into polished, geometry-checked SVG diagrams, high-resolution PNGs, validated SVG-to-GIF semantic motion, and offline interactive HTML. The focused animation path accepts a generated semantic SVG and emits one compact, probed GIF. It ships with **11 generator-backed styles** and **1 AI-authored style (Dark Luxury)**. Four engineering-first styles add executable contracts for C4 reviews, cloud deployments, event streams, and reliability investigations, alongside deep AI/Agent domain patterns and all 14 UML diagram types.
  22. ```
  23. User: "Generate a Mem0 memory architecture diagram, dark style"
  24. → Skill classifies: Memory Architecture Diagram, Style 2
  25. → Generates SVG with swim lanes, cylinders, semantic arrows
  26. → Exports 1920px PNG
  27. → Reports: mem0-architecture.svg / mem0-architecture.png
  28. ```
  29. ---
  30. ## Sponsors
  31. <table>
  32. <tr>
  33. <td width="200" align="center"><a href="https://aigocode.app/invite/yizhiyanhua"><img src="assets/sponsors/aigocode.png" alt="AIGoCode" width="160" /></a></td>
  34. <td>Thanks to <strong>AIGoCode</strong> for sponsoring this project! AIGoCode is an all-in-one platform that integrates Claude Code, Codex, and the latest Gemini models, providing you with stable, efficient, and highly cost-effective AI coding services. The sponsor advertises flexible subscriptions and direct access without a VPN; availability and account conditions follow its own service terms. AIGoCode has prepared a special benefit for <strong>fireworks-tech-graph</strong> users: if you register via <a href="https://aigocode.app/invite/yizhiyanhua">this link</a>, you'll receive an extra <strong>10% bonus credit</strong> on your first top-up!</td>
  35. </tr>
  36. </table>
  37. Interested in becoming a sponsor? Contact: <a href="mailto:ccc7574@gmail.com">ccc7574@gmail.com</a>
  38. ---
  39. ## Work With the Builder
  40. This project is also a proof surface for a broader capability: turning vague AI/devtool workflows into constrained, reusable systems with validation, documentation, export paths, and product-facing polish.
  41. If you are building agent infrastructure, AI IDEs, internal copilots, developer tools, technical documentation systems, or applied AI workflow products, I am open to scoped paid sprints, design-partner work, and founding engineer conversations.
  42. - Founder-facing profile: https://bradzhang.dev/en
  43. - Commercial case study: https://bradzhang.dev/en/case-studies/fireworks-tech-graph
  44. - Work with me: https://bradzhang.dev/en/work-with-me
  45. ---
  46. ## Showcase
  47. > The animated previews use the user-approved 5.75-second settled-flow timeline: routes draw in first, then the final topology keeps live data moving for two additional seconds. Each full-size GIF is 960px wide at 20fps / 115 frames; the 3×4 overview is an optimized 1200px preview. Lossless 1920px PNGs remain in `assets/samples/` as static regression baselines.
  48. ![Animated 12-style showcase — one distinct engineering scenario per style](assets/samples/showcase-12-styles.gif)
  49. The v1.2.0 overview above and every full-size animated sample below come from the approved regression set. Each style keeps a distinct scenario while sharing the same geometry, text-fit, wire-routing, and semantic-motion quality gates.
  50. ### Style 1 — Flat Icon (default)
  51. *Mem0 Memory Architecture — personal-memory extraction, conflict resolution, storage, and retrieval*
  52. ![Style 1 — Flat Icon](assets/samples/sample-style1-flat.gif)
  53. ### Style 2 — Dark Terminal
  54. *Tool Call Flow — dark terminal execution, source grounding, retrieval, and answer synthesis*
  55. ![Style 2 — Dark Terminal](assets/samples/sample-style2-dark.gif)
  56. ### Style 3 — Blueprint
  57. *Microservices Architecture — engineering grid, domain services, data stores, events, and telemetry*
  58. ![Style 3 — Blueprint](assets/samples/sample-style3-blueprint.gif)
  59. ### Style 4 — Notion Clean
  60. *Agent Memory Types — minimal hierarchy from sensory and working context to durable memory*
  61. ![Style 4 — Notion Clean](assets/samples/sample-style4-notion.gif)
  62. ### Style 5 — Glassmorphism
  63. *Multi-Agent Collaboration — coordinator, specialists, shared state, review, and synthesis*
  64. ![Style 5 — Glassmorphism](assets/samples/sample-style5-glass.gif)
  65. ### Style 6 — Claude Official
  66. *System Architecture — warm interface, runtime, safety, memory, tools, and operations layers*
  67. ![Style 6 — Claude Official](assets/samples/sample-style6-claude.gif)
  68. ### Style 7 — OpenAI Official
  69. *API Integration Flow — clean SDK, prompt, model, tool, delivery, and release stages*
  70. ![Style 7 — OpenAI Official](assets/samples/sample-style7-openai.gif)
  71. ### Style 8 — Dark Luxury *(AI-authored)*
  72. *Agent Runtime Architecture — control plane, execution and state layers, champagne-gold structure, semantic color buckets*
  73. ![Style 8 — Dark Luxury](assets/samples/sample-style8-dark-luxury.gif)
  74. ### Style 9 — C4 Review Canvas
  75. *Checkout Container Review — one abstraction level, explicit responsibilities, technologies, and protocols*
  76. ![Style 9 — C4 Review Canvas](assets/samples/sample-style9-c4-review-canvas.gif)
  77. ### Style 10 — Cloud Fabric
  78. *Active–Active Checkout Deployment — global ingress, regions, VPC ownership, and cross-region replication*
  79. ![Style 10 — Cloud Fabric](assets/samples/sample-style10-cloud-fabric.gif)
  80. ### Style 11 — Event Transit
  81. *Checkout Event Line — topics as rails, processors as stations, a declared junction, DLQ, and state projection*
  82. ![Style 11 — Event Transit](assets/samples/sample-style11-event-transit.gif)
  83. ### Style 12 — Ops Pulse
  84. *Checkout Reliability Pulse — golden signals, one critical path, OTel export, and a correlated trace*
  85. ![Style 12 — Ops Pulse](assets/samples/sample-style12-ops-pulse.gif)
  86. ---
  87. ## Stable Prompt Recipe
  88. The public showcase keeps a distinct domain scene for every style. They remain comparable because every fixture passes the same executable composition contract. A same-topology regression set remains internal under `fixtures/quality-baseline/`.
  89. ```text
  90. Draw the scenario assigned to style N:
  91. 1 Mem0 Memory Architecture; 2 Tool Call Flow; 3 Microservices Architecture;
  92. 4 Agent Memory Types; 5 Multi-Agent Collaboration; 6 System Architecture;
  93. 7 API Integration Flow; 8 Agent Runtime Architecture; 9 C4 Checkout Review;
  94. 10 Active–Active Cloud Deployment; 11 Checkout Event Line; 12 Checkout Reliability Pulse.
  95. Preserve the scenario-specific nodes, sections, and reading direction.
  96. Apply the showcase composition contract: zero crossings, zero bridge jumps, at most two bends per edge,
  97. at most eight bends overall, at least 40px between nodes, at least 20px container gutter,
  98. short orthogonal segments, and labels kept clear of nodes, routes, and section headers.
  99. Preserve the selected style's typography, palette, card material, and brand details.
  100. ```
  101. For the four engineering-first styles, use one of these prompt fingerprints so
  102. the router selects the domain contract as well as the visual theme:
  103. ```text
  104. Style 9 · C4 review board: show one C4 level, responsibilities, technologies, review state, and relationship protocols.
  105. Style 10 · Multi-region deployment map: show global ingress, Region/VPC ownership, neutral cloud glyphs, deployment mode, and named boundary mechanisms.
  106. Style 11 · Event metro map: show thin topic rails, numbered processor stations, declared junctions, consumer groups, DLQ, and state projections.
  107. Style 12 · Reliability pulse: show one observation window, four golden signals per service, numbered critical hops, telemetry export, and one correlated trace.
  108. ```
  109. Replace `N` with `1`–`12`. Style 8 remains AI-authored and loads `references/style-8-dark-luxury.md`; Styles 9–12 also enforce their engineering semantic contract. All styles load `references/composition-quality-contract.md`.
  110. ---
  111. ## Features
  112. - **12 visual styles** — 11 generator-backed profiles + 1 AI-authored style (Dark Luxury)
  113. - **Engineering semantic contracts** — C4 abstraction levels, deployment ownership, event-rail topology, and exact golden signals fail closed before rendering
  114. - **Executable style system** — style guides are encoded into the generator, not only documented in markdown
  115. - **Shared composition-quality contract** — every official style enforces zero crossings/bridges, ≤2 bends per edge, route-stretch, spacing, gutter, micro-segment, and label-clearance budgets
  116. - **14 diagram types** — Full UML support (Class, Component, Deployment, Package, Composite Structure, Object, Use Case, Activity, State Machine, Sequence, Communication, Timing, Interaction Overview, ER Diagram) plus AI/Agent domain diagrams
  117. - **AI/Agent domain patterns** — RAG, Agentic Search, Mem0, Multi-Agent, Tool Call, and more built-in
  118. - **Semantic shape vocabulary** — LLM = double-border rect, Agent = hexagon, Vector Store = ringed cylinder
  119. - **Semantic arrow system** — color + dash pattern encode meaning (write vs read vs async vs loop)
  120. - **Geometry-safe routing** — deterministic orthogonal routes, exact waypoints, distinct ports, automatic legend relocation, labels kept inside the canvas, and verified bridge jumps for unavoidable crossings
  121. - **Versioned diagram IR** — legacy JSON normalizes to schema v1; duplicate IDs, dangling references, malformed waypoints, and non-finite geometry fail before rendering
  122. - **Structured SVG validation** — XML and marker integrity plus semantic node, reserved-region, label, canvas, edge-overlap, and edge-crossing checks
  123. - **Unified CLI + interactive export** — render, validate, inspect, and export one offline HTML file with pan/zoom, themes, copy, and SVG/PNG/JPEG/WebP output up to 4×
  124. - **Focused semantic GIF motion** — generated SVG in, validated GIF out; connectors begin absent and draw in semantic order. All twelve style contracts are user-approved. The shared `+2s-settled-flow` timing revision is also user-approved, so the default 5.75s/115-frame loop holds full settled flow on frames 38–109, then resets on 110–114
  125. - **Visual review gate** — exported PNGs are inspected for clipping, overlap, label placement, and routing regressions before delivery
  126. - **Product icons** — 40+ products with brand colors: OpenAI, Anthropic, Pinecone, Weaviate, Kafka, PostgreSQL…
  127. - **Swim lane grouping** — automatic layer labeling for complex architectures
  128. - **SVG + PNG output** — SVG for editing, 1920px PNG for embedding
  129. - **Renderer-friendly** — pure inline SVG, no external font fetching; renders cleanly in cairosvg, rsvg-convert, and headless Chrome
  130. ---
  131. ## Loop Engineering
  132. The first render is treated as a candidate, not an automatic final result. `fireworks-tech-graph` uses an agent-driven, bounded validation feedback loop to move each diagram toward a verified deliverable:
  133. ```text
  134. Prompt
  135. → Diagram Contract
  136. → Semantic IR
  137. → Style Spec
  138. → Route Planner
  139. → SVG Build
  140. → Structural Validation
  141. → PNG Visual Readback
  142. → Targeted Revision
  143. → Verified SVG + PNG
  144. ```
  145. The loop follows five design principles:
  146. 1. **Evaluate, don't assert** — completion is backed by validator and render evidence, not by the model saying the diagram looks correct.
  147. 2. **Deterministic checks first** — XML structure, marker integrity, path geometry, arrow-component collisions, and renderability are checked before visual judgment.
  148. 3. **Perceptual validation second** — the exported PNG is read back to inspect clipping, label collisions, hierarchy, whitespace, and routing quality that syntax checks cannot see.
  149. 4. **Targeted correction** — each pass changes only the diagnosed labels, coordinates, corridors, or spacing, then reruns validation and rendering.
  150. 5. **Bounded convergence** — visual review allows at most two focused correction passes by default, preventing an unbounded self-editing loop.
  151. The loop is observable in the final status:
  152. ```text
  153. validation: passed
  154. visual_review: passed
  155. ```
  156. If the runtime cannot read images, the skill reports `visual_review: skipped (image reader unavailable)` explicitly. The workflow remains bounded and auditable; it does not claim visual verification without image evidence.
  157. ---
  158. ## Installation
  159. ### Recommended: install the complete skill for both runtimes
  160. Use the real nested skill path. The final `/skills/fireworks-tech-graph` segment is required because a bare repository install can select only the root `SKILL.md` in current versions of `skills` CLI.
  161. ```bash
  162. npx -y skills@1.5.17 add \
  163. yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph \
  164. --agent codex claude-code -g -y --copy
  165. ```
  166. This creates complete copies at `~/.agents/skills/fireworks-tech-graph` for Codex and `~/.claude/skills/fireworks-tech-graph` for Claude Code, including scripts, schemas, fixtures, templates, tests, references, and metadata.
  167. ### Editable Git checkout for Codex
  168. ```bash
  169. mkdir -p ~/.agents/skills
  170. git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.agents/skills/fireworks-tech-graph
  171. ```
  172. Codex discovers personal skills from `~/.agents/skills` and reads the optional `agents/openai.yaml` metadata included in this repository.
  173. ### Editable Git checkout for Claude Code
  174. ```bash
  175. mkdir -p ~/.claude/skills
  176. git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.claude/skills/fireworks-tech-graph
  177. ```
  178. Claude Code discovers personal skills from `~/.claude/skills` and ignores the Codex-only UI metadata.
  179. ### One editable checkout shared by Codex and Claude Code
  180. For a fresh install with Claude Code 2.1.203 or newer, keep one checkout and link both discovery paths to it. Move any existing destinations aside before creating the links.
  181. ```bash
  182. mkdir -p ~/.local/share/agent-skills ~/.agents/skills ~/.claude/skills
  183. git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.local/share/agent-skills/fireworks-tech-graph
  184. ln -s ~/.local/share/agent-skills/fireworks-tech-graph ~/.agents/skills/fireworks-tech-graph
  185. ln -s ~/.local/share/agent-skills/fireworks-tech-graph ~/.claude/skills/fireworks-tech-graph
  186. ```
  187. This keeps `SKILL.md`, references, scripts, templates, and future updates identical in both agents. The npm registry is a separate distribution channel and may lag GitHub Releases. For the current Skill version, use the nested GitHub path above; the npm page remains available for package metadata:
  188. ```text
  189. https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph
  190. ```
  191. ## Update
  192. For a `skills` CLI copy, rerun the recommended nested-path command. For Git installations, update whichever checkout you installed:
  193. ```bash
  194. git -C ~/.agents/skills/fireworks-tech-graph pull
  195. # or
  196. git -C ~/.claude/skills/fireworks-tech-graph pull
  197. # or, for the shared checkout
  198. git -C ~/.local/share/agent-skills/fireworks-tech-graph pull
  199. ```
  200. After the first install, restart Codex and Claude Code so both discover the skill. Later `SKILL.md` edits are detected automatically; restart the runtime after changing bundled scripts or references if the update is not visible.
  201. The shell commands above target macOS, Linux, WSL, and Git Bash. On native Windows, use the equivalent `%USERPROFILE%\.agents\skills` and `%USERPROFILE%\.claude\skills` paths. Python 3.9+ is required; the optional Puppeteer path requires Node.js 22.12+.
  202. ---
  203. ## Unified CLI
  204. ```bash
  205. SKILL_ROOT="${CLAUDE_SKILL_DIR:-$HOME/.agents/skills/fireworks-tech-graph}"
  206. python3 "$SKILL_ROOT/scripts/fireworks.py" doctor
  207. python3 "$SKILL_ROOT/scripts/fireworks.py" validate architecture "$SKILL_ROOT/fixtures/api-flow-style7.json"
  208. python3 "$SKILL_ROOT/scripts/fireworks.py" render architecture "$SKILL_ROOT/fixtures/api-flow-style7.json" diagram.svg --report layout.json
  209. python3 "$SKILL_ROOT/scripts/fireworks.py" check diagram.svg
  210. python3 "$SKILL_ROOT/scripts/fireworks.py" export-html diagram.svg diagram.html --title "Agent Runtime Architecture"
  211. python3 "$SKILL_ROOT/scripts/fireworks.py" animate diagram.svg diagram.gif
  212. ```
  213. The HTML export is one offline file. It sanitizes the SVG, adds pan/zoom/reset, light and dark themes, SVG source copy, and SVG/PNG/JPEG/WebP downloads at 1×–4×.
  214. For motion, say **“Generate a GIF”**, **“Animate this diagram”**, `生成 GIF`, `制作 GIF`, or `让这张图动起来`. The command accepts a generated semantic SVG that carries one of the twelve approved motion contracts. Exact source bytes are not pinned, so validated title and content variants of a supported topology work; missing or changed role/stage/order coverage, route direction, required colors, or geometry fails closed. GIF is the only motion media format, and the default command also writes `<output>.motion.json` as its verification report. The approved default is 960px, 5.75 seconds, 20fps, and 115 frame-center samples. All twelve scenes start connector-free, draw routes on frames 1–36, fade live flow on 36–38, hold full settled flow on 38–109, and reset on 110–114. Their approved identities include the packet heads, terminal evidence trace, Blueprint registration beads, 14×10 Notion memory cards, and the eight scene-specific signatures listed below. Default packages report both the style contract and shared `+2s-settled-flow` timing revision as `user-approved`. Timelines of 75 frames or fewer remain all-unique. Longer timelines allow non-adjacent repeated rasters inside the full-opacity interval; frame 110 is the sole boundary exception because its unchanged reset opacity is exactly 1.00, and such evidence is classified as `intentional_reset_boundary_repeat`. Frames 111–114 remain globally distinct. Long timelines require at least 75 unique rasters and forbid adjacent duplicates. The all-style 75-vs-115 gate counts binary-exact and decoded-RGBA-exact frames separately; compositor-only fallback is accepted only at AE ≤ 128, normalized RMSE ≤ 0.001, with components no thicker than 2px and confined to edge or node borders. DOM and signature geometry remain strict-exact. Explicit 3.75s/75-frame and 2.75s/55-frame calls remain supported. See [Focused SVG-to-GIF Motion](references/motion-effects.md).
  215. | Style | Preset | Live signature |
  216. |---:|---|---|
  217. | 5 | `agent-orchestration` | glass task capsule + coordinator halo |
  218. | 6 | `governed-runtime` | governance thread + policy seal |
  219. | 7 | `token-stream` | API rail + three-cell token train |
  220. | 8 | `golden-circuit` | luxury circuit rail + gem tracer |
  221. | 9 | `review-trace` | review rail + moving review cursor |
  222. | 10 | `cloud-flow` | region chevrons + replication capsule |
  223. | 11 | `event-transit` | event train + exception/projection cars |
  224. | 12 | `ops-pulse` | ECG/export heads + trace reveal + waterfall scanner |
  225. ---
  226. ## Requirements
  227. The bundled SVG/PNG scripts require **cairosvg** (recommended) or `rsvg-convert`. Optional SVG-to-GIF export requires FFmpeg/FFprobe, Chrome/Chromium, and `puppeteer` or `puppeteer-core`.
  228. ```bash
  229. # Recommended: cairosvg (best CSS support)
  230. python3 -m pip install cairosvg
  231. # Fallback: rsvg-convert (system package; may drop CSS / <foreignObject>)
  232. brew install librsvg # macOS
  233. sudo apt install librsvg2-bin # Ubuntu/Debian
  234. # Optional semantic motion export. Install beside every copied Skill because the
  235. # renderer intentionally does not load modules from the caller's directory.
  236. brew install ffmpeg # macOS; use your system package manager elsewhere
  237. for SKILL_ROOT in \
  238. "$HOME/.agents/skills/fireworks-tech-graph" \
  239. "$HOME/.claude/skills/fireworks-tech-graph"
  240. do
  241. [ -d "$SKILL_ROOT" ] || continue
  242. npm install --prefix "$SKILL_ROOT" --ignore-scripts --no-save --package-lock=false puppeteer-core@25.3.0
  243. python3 "$SKILL_ROOT/scripts/fireworks.py" doctor
  244. done
  245. # Verify either supported script renderer
  246. python3 -c "import cairosvg; print(cairosvg.__version__)"
  247. rsvg-convert --version
  248. ```
  249. | Renderer | Quality | Install Cost | Use When |
  250. |----------|---------|--------------|----------|
  251. | **cairosvg** | ✅ Good | Single `python3 -m pip install` | Default — best balance |
  252. | rsvg-convert | ⚠️ Fair | System package | No Python available, simple flat diagrams |
  253. | puppeteer | ✅✅ Best | Node + Chromium | Manual browser-rendering path for D3, Mermaid, or pixel-perfect output |
  254. ---
  255. ## Why Not Mermaid or draw.io?
  256. | | Mermaid | draw.io | **fireworks-tech-graph** |
  257. |--|---------|---------|--------------------------|
  258. | Natural language input | ✗ | ✗ | ✅ |
  259. | AI/Agent domain patterns | ✗ | ✗ | ✅ |
  260. | Multiple visual styles | ✗ | manual | ✅ 12 built-in |
  261. | High-res PNG export | ✗ | manual | ✅ auto 1920px |
  262. | Semantic arrow colors | ✗ | manual | ✅ auto |
  263. | No online tool needed | ✅ | ✗ | ✅ |
  264. Mermaid is great for quick inline diagrams in markdown. draw.io is great for manual polishing. `fireworks-tech-graph` is optimized for **describing a system and getting a polished diagram immediately**, without writing DSL syntax or clicking around a GUI.
  265. ---
  266. ## Usage
  267. ### Trigger phrases
  268. The skill auto-triggers on:
  269. ```
  270. generate diagram / draw diagram / create chart / visualize
  271. architecture diagram / flowchart / sequence diagram / data flow
  272. Generate a GIF / animate this diagram / animate this SVG as a GIF / 生成 GIF / 制作 GIF / 让这张图动起来 / 把刚才的 SVG 转成 GIF
  273. ```
  274. ### Basic usage
  275. ```
  276. Draw a RAG pipeline flowchart
  277. ```
  278. ```
  279. Generate an Agentic Search architecture diagram
  280. ```
  281. ### Specify style
  282. ```
  283. Draw a microservices architecture diagram, style 2 (dark terminal)
  284. ```
  285. ```
  286. Draw a multi-agent collaboration diagram --style glassmorphism
  287. ```
  288. ### Specify output path
  289. ```
  290. Generate a Mem0 architecture diagram, output to ~/Desktop/
  291. ```
  292. ```
  293. Create a tool call flow diagram --output /tmp/diagrams/
  294. ```
  295. ---
  296. ## Example Prompts by Scenario
  297. ### AI/Agent Systems
  298. ```
  299. Compare Agentic RAG vs standard RAG in a feature matrix, Notion clean style
  300. ```
  301. → Comparison matrix: RAG vs Agentic RAG, covering retrieval strategy, agent loop, tool use
  302. ```
  303. Generate a Mem0 memory architecture diagram with vector store, graph DB, KV store, and memory manager
  304. ```
  305. → Memory Architecture with swim lanes: Input → Memory Manager → Storage tiers → Retrieval
  306. ```
  307. Draw a Multi-Agent diagram: Orchestrator dispatches 3 SubAgents (search / compute / code execution), results aggregated
  308. ```
  309. → Agent Architecture with hexagons, tool layers, and result aggregation
  310. ```
  311. Visualize the Tool Call execution flow: LLM → Tool Selector → Execution → Parser → back to LLM
  312. ```
  313. → Flowchart with decision loop showing tool invocation cycle
  314. ```
  315. Draw the 5 agent memory types: Sensory, Working, Episodic, Semantic, Procedural
  316. ```
  317. → Mind map or layered architecture showing memory tiers from sensory to procedural
  318. ### Infrastructure & Cloud
  319. ```
  320. Draw a microservices architecture: Client → API Gateway → [User Service / Order Service / Payment Service] → PostgreSQL + Redis
  321. ```
  322. → Architecture diagram with horizontal layers, swim lanes per service cluster
  323. ```
  324. Generate a data pipeline diagram: Kafka → Spark processing → write to S3 → Athena query
  325. ```
  326. → Data flow diagram with labeled arrows (stream / batch / query)
  327. ```
  328. Draw a Kubernetes deployment: Ingress → Service → [Pod × 3] → ConfigMap + PersistentVolume
  329. ```
  330. → Architecture with dashed containers per namespace, solid arrows for traffic flow
  331. ### API & Sequence Flows
  332. ```
  333. Draw an OAuth2 authorization code flow sequence diagram: User → Client → Auth Server → Resource Server
  334. ```
  335. → Sequence diagram with vertical lifelines and activation boxes
  336. ```
  337. Draw the ChatGPT Plugin call sequence diagram
  338. ```
  339. → Sequence: User → ChatGPT → Plugin Manifest → API → Response chain
  340. ### Decision & Process Flows
  341. ```
  342. Draw a pre-launch QA flowchart for an AI app: Code Review → Security Scan → Performance Test → Manual Approval → Deploy
  343. ```
  344. → Flowchart with diamond decision nodes and parallel branches
  345. ```
  346. Generate a feature comparison matrix: RAG vs Fine-tuning vs Prompt Engineering
  347. ```
  348. → Comparison matrix with checked/unchecked cells across cost, latency, accuracy, flexibility
  349. ### Concept Maps
  350. ```
  351. Visualize the LLM application tech stack: from foundation model to SDK to app framework to deployment
  352. ```
  353. → Layered architecture or mind map from model layer to product layer
  354. ```
  355. Draw an AI Agent capability map: Perception / Memory / Reasoning / Action / Learning
  356. ```
  357. → Mind map with central "AI Agent" node and 5 radial branches
  358. ---
  359. ## 12 Styles
  360. | # | Name | Background | Font | Best For |
  361. |---|------|-----------|------|----------|
  362. | 1 | **Flat Icon** *(default)* | `#ffffff` | Helvetica | Blogs, slides, docs |
  363. | 2 | **Dark Terminal** | `#0f0f1a` | SF Mono / Fira Code | GitHub README, dev articles |
  364. | 3 | **Blueprint** | `#0a1628` | Courier New | Architecture docs, engineering |
  365. | 4 | **Notion Clean** | `#ffffff` | system-ui | Notion, Confluence, wikis |
  366. | 5 | **Glassmorphism** | `#0d1117` gradient | Inter | Product sites, keynotes |
  367. | 6 | **Claude Official** | `#f8f6f3` | system-ui | Anthropic-style diagrams, warm aesthetic |
  368. | 7 | **OpenAI Official** | `#ffffff` | system-ui | OpenAI-style diagrams, clean modern look |
  369. | 8 | **Dark Luxury** *(AI-authored)* | `#0a0a0a` | Georgia + system-ui | Premium docs, README heroes, conference slides |
  370. | 9 | **C4 Review Canvas** | `#f7f2e8` | Avenir / system-ui | C4 design reviews, ADRs, responsibilities |
  371. | 10 | **Cloud Fabric** | `#edf5fb` | Inter / system-ui | Multi-region deployments, VPC/network ownership |
  372. | 11 | **Event Transit** | `#fbf7ee` | Avenir / system-ui | Kafka/event streams, consumer groups, DLQ |
  373. | 12 | **Ops Pulse** | `#07111f` | SF Mono / Fira Code | SRE reviews, golden signals, critical traces |
  374. Each style has a dedicated reference file in `references/` with exact color tokens and SVG patterns. Styles 1–7 and 9–12 are generator-backed; Style 8 uses AI-authored composition plus a static regression fixture.
  375. The generator consumes structure fields such as `containers`, semantic `nodes[].kind`, `arrows[].flow`, and explicit port anchors. Styles 9–12 additionally validate domain-specific fields before layout.
  376. Useful high-leverage fields for style-specific polish:
  377. - `style_overrides` to nudge title alignment or palette tokens without forking a full style
  378. - `containers[].header_prefix` / `containers[].header_text` for blueprint-style numbered section headers such as `01 // EDGE`
  379. - `containers[].side_label` for Claude-style left layer labels
  380. - `window_controls`, `meta_left`, `meta_center`, `meta_right` for terminal / document chrome
  381. - `blueprint_title_block` for engineering title boxes in style 3
  382. ### Style Selection Guide
  383. **For UML Diagrams:**
  384. - **Class/Component/Package**: Style 1 (Flat Icon) or Style 4 (Notion Clean) — clear structure, easy to read
  385. - **Sequence/Timing**: Style 2 (Dark Terminal) — monospace fonts help with alignment
  386. - **State Machine/Activity**: Style 3 (Blueprint) — engineering aesthetic fits process flows
  387. - **Use Case/Interview**: Style 1 (Flat Icon) — colorful, accessible
  388. **For AI/Agent Diagrams:**
  389. - **RAG/Agentic Search**: Style 2 (Dark Terminal) or Style 5 (Glassmorphism) — tech-forward aesthetic
  390. - **Memory Architecture**: Style 3 (Blueprint) — emphasizes layered storage tiers
  391. - **Multi-Agent**: Style 5 (Glassmorphism) — frosted cards distinguish agent boundaries
  392. **For Documentation:**
  393. - **Internal docs**: Style 4 (Notion Clean) — minimal, wiki-friendly
  394. - **Blog posts**: Style 1 (Flat Icon) — colorful, engaging
  395. - **GitHub README**: Style 2 (Dark Terminal) — matches dark theme
  396. - **Presentations**: Style 5 (Glassmorphism) or Style 6 (Claude Official) — polished
  397. **For Engineering Reviews:**
  398. - **C4/ADR review**: Style 9 (C4 Review Canvas) — one declared abstraction level with responsibilities and protocols
  399. - **Cloud deployment review**: Style 10 (Cloud Fabric) — explicit region/network ownership and cross-boundary mechanisms
  400. - **Event-driven system review**: Style 11 (Event Transit) — topic rails, processors, consumer groups, state, and DLQ
  401. - **Reliability/incident review**: Style 12 (Ops Pulse) — golden signals, one critical path, and a correlated trace
  402. **Brand-Specific:**
  403. - **Anthropic/Claude projects**: Style 6 (Claude Official) — warm cream background, brand colors
  404. - **OpenAI projects**: Style 7 (OpenAI Official) — clean white, OpenAI palette
  405. - **Premium editorial diagrams**: Style 8 (Dark Luxury) — deep black canvas, champagne-gold hierarchy, semantic color buckets
  406. ---
  407. ## Diagram Types
  408. | Type | Description | Key Layout Rule |
  409. |------|-------------|-----------------|
  410. | **Architecture** | Services, components, cloud infra | Horizontal layers top→bottom |
  411. | **Data Flow** | What data moves where | Label every arrow with data type |
  412. | **Flowchart** | Decisions, process steps | Diamond = decision, top→bottom |
  413. | **Agent Architecture** | LLM + tools + memory | 5-layer model: Input/Agent/Memory/Tool/Output |
  414. | **Memory Architecture** | Mem0, MemGPT-style | Separate read/write paths, memory tiers |
  415. | **Sequence** | API call chains, time-ordered | Vertical lifelines, horizontal messages |
  416. | **Comparison** | Feature matrix, side-by-side | Column = system, row = attribute |
  417. | **Mind Map** | Concept maps, radial | Central node, bezier branches |
  418. ### UML Diagram Support (14 Types)
  419. | UML Type | Description | Best Style |
  420. |----------|-------------|------------|
  421. | **Class Diagram** | Classes, attributes, methods, relationships | Style 1, 4 |
  422. | **Component Diagram** | Software components and dependencies | Style 1, 3 |
  423. | **Deployment Diagram** | Hardware nodes and software deployment | Style 3 |
  424. | **Package Diagram** | Package organization and dependencies | Style 1, 4 |
  425. | **Composite Structure** | Internal structure of classes/components | Style 1, 3 |
  426. | **Object Diagram** | Object instances and relationships | Style 1, 4 |
  427. | **Use Case Diagram** | Actors, use cases, system boundaries | Style 1 |
  428. | **Activity Diagram** | Workflows, parallel processes | Style 3 |
  429. | **State Machine** | State transitions and events | Style 2, 3 |
  430. | **Sequence Diagram** | Message exchanges over time | Style 2 |
  431. | **Communication Diagram** | Object interactions and messages | Style 1, 2 |
  432. | **Timing Diagram** | State changes over time | Style 2 |
  433. | **Interaction Overview** | High-level interaction flow | Style 1, 2 |
  434. | **ER Diagram** | Entity-relationship data models | Style 1, 3 |
  435. ---
  436. ## AI/Agent Domain Patterns
  437. Built-in pattern knowledge:
  438. ```
  439. RAG Pipeline → Query → Embed → VectorSearch → Retrieve → LLM → Response
  440. Agentic RAG → adds Agent loop + Tool use
  441. Agentic Search → Query → Planner → [Search/Calc/Code] → Synthesizer
  442. Mem0 Memory Layer → Input → Memory Manager → [VectorDB + GraphDB] → Context
  443. Agent Memory Types → Sensory → Working → Episodic → Semantic → Procedural
  444. Multi-Agent → Orchestrator → [SubAgent×N] → Aggregator → Output
  445. Tool Call Flow → LLM → Tool Selector → Execution → Parser → LLM (loop)
  446. ```
  447. ---
  448. ## Shape Vocabulary
  449. Shapes encode semantic meaning consistently across all styles:
  450. | Concept | Shape |
  451. |---------|-------|
  452. | User / Human | Circle + body |
  453. | LLM / Model | Rounded rect, double border, ⚡ |
  454. | Agent / Orchestrator | Hexagon |
  455. | Memory (short-term) | Dashed-border rounded rect |
  456. | Memory (long-term) | Solid cylinder |
  457. | Vector Store | Cylinder with inner rings |
  458. | Graph DB | 3-circle cluster |
  459. | Tool / Function | Rect with ⚙ |
  460. | API / Gateway | Hexagon (single border) |
  461. | Queue / Stream | Horizontal pipe/tube |
  462. | Document / File | Folded-corner rect |
  463. | Browser / UI | Rect with 3-dot titlebar |
  464. | Decision | Diamond |
  465. | External Service | Dashed-border rect |
  466. ---
  467. ## Arrow Semantics
  468. | Flow Type | Stroke | Dash | Meaning |
  469. |-----------|--------|------|---------|
  470. | Primary data flow | 2px solid | — | Main request/response |
  471. | Control / trigger | 1.5px solid | — | System A triggers B |
  472. | Memory read | 1.5px solid | — | Retrieve from store |
  473. | Memory write | 1.5px | `5,3` | Write/store operation |
  474. | Async / event | 1.5px | `4,2` | Non-blocking |
  475. | Feedback / loop | 1.5px curved | — | Iterative reasoning |
  476. ---
  477. ## File Structure
  478. ```
  479. fireworks-tech-graph/
  480. ├── SKILL.md # Main skill — diagram types, layout rules, shape vocab
  481. ├── README.md # This file (English)
  482. ├── README.zh.md # Chinese version
  483. ├── references/
  484. │ ├── style-1-flat-icon.md # White background, colored accents
  485. │ ├── style-2-dark-terminal.md # Dark bg, neon accents, monospace
  486. │ ├── style-3-blueprint.md # Blueprint grid, cyan lines
  487. │ ├── style-4-notion-clean.md # Minimal, white, single arrow color
  488. │ ├── style-5-glassmorphism.md # Dark gradient, frosted glass cards
  489. │ ├── style-6-claude-official.md # Warm cream background, Anthropic brand
  490. │ ├── style-7-openai.md # Clean white, OpenAI brand palette
  491. │ ├── style-8-dark-luxury.md # Deep black, champagne gold, AI-authored layout
  492. │ ├── style-9-c4-review-canvas.md # C4 review semantics + deterministic rough marks
  493. │ ├── style-10-cloud-fabric.md # Deployment ownership + neutral cloud glyphs
  494. │ ├── style-11-event-transit.md # Topic rails, stations, junctions, and DLQ
  495. │ ├── style-12-ops-pulse.md # Golden signals, critical path, and trace waterfall
  496. │ ├── png-export.md # Renderer selection and manual export paths
  497. │ └── icons.md # 40+ product icons + semantic shapes
  498. ├── agents/
  499. │ └── openai.yaml # Optional Codex UI metadata
  500. ├── schemas/ # Versioned diagram JSON Schemas
  501. ├── docs/ # Capability contract and roadmap
  502. ├── examples/
  503. │ └── interactive-architecture.html # Offline pan/zoom/export demo
  504. ├── fixtures/
  505. │ ├── mem0-style1.json # Style 1 · Mem0 memory scene
  506. │ ├── tool-call-style2.json # Style 2 · grounded tool-call scene
  507. │ ├── microservices-style3.json # Style 3 · microservices blueprint
  508. │ ├── agent-memory-types-style4.json # Style 4 · memory hierarchy
  509. │ ├── multi-agent-style5.json # Style 5 · specialist collaboration
  510. │ ├── system-architecture-style6.json # Style 6 · layered system
  511. │ ├── api-flow-style7.json # Style 7 · API integration
  512. │ ├── dark-luxury-style8.svg # Style 8 · AI-authored runtime scene
  513. │ ├── c4-review-canvas-style9.json # Style 9 · Checkout C4 review
  514. │ ├── cloud-fabric-style10.json # Style 10 · Active-active deployment
  515. │ ├── event-transit-style11.json # Style 11 · Checkout event line
  516. │ ├── ops-pulse-style12.json # Style 12 · Reliability pulse
  517. │ └── quality-baseline/ # Internal same-topology regression set
  518. ├── scripts/
  519. │ ├── fireworks.py # Unified validate/render/check/animate/export CLI
  520. │ ├── diagram_ir.py # Typed schema-v1 normalization
  521. │ ├── fireworks_geometry.py # Shared routing and collision semantics
  522. │ ├── interactive_html.py # Sanitized offline HTML exporter
  523. │ ├── generate-diagram.sh # Validate SVG + export PNG
  524. │ ├── generate-from-template.py # Create starter SVGs from templates
  525. │ ├── motion.py # SVG-to-GIF validation, encoding, and atomic reports
  526. │ ├── svg2gif.js # Manual-timeline Chromium frame renderer
  527. │ ├── svg2png.js # High-fidelity Puppeteer exporter
  528. │ ├── validate-svg.sh # Validation and render-check entrypoint
  529. │ ├── validate_svg.py # XML, marker, transform, and path collision checks
  530. │ └── test-all-styles.sh # Batch test all styles
  531. ├── tests/
  532. │ ├── test_geometry_contracts.py # Router and artifact geometry gates
  533. │ └── ... # IR, CLI, exporter, installer compatibility
  534. ├── tools/ # Distribution, consistency, install canary
  535. ├── skills/fireworks-tech-graph/ # Complete npx-compatible physical mirror
  536. ├── assets/
  537. │ └── samples/ # Showcase diagram PNGs
  538. ├── templates/
  539. │ ├── architecture.svg # Architecture starter template
  540. │ ├── data-flow.svg # Data-flow starter template
  541. │ └── ... # Additional diagram templates
  542. └── agentloop-core.svg # Included sample SVG
  543. ```
  544. ---
  545. ## Product Icon Coverage
  546. **AI/ML:** OpenAI, Anthropic/Claude, Google Gemini, Meta LLaMA, Mistral, Cohere, Groq, Hugging Face
  547. **AI Frameworks:** Mem0, LangChain, LlamaIndex, LangGraph, CrewAI, AutoGen, DSPy, Haystack
  548. **Vector DBs:** Pinecone, Weaviate, Qdrant, Chroma, Milvus, pgvector, Faiss
  549. **Databases:** PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch, Neo4j, Cassandra
  550. **Messaging:** Kafka, RabbitMQ, NATS, Pulsar
  551. **Cloud:** AWS, GCP, Azure, Cloudflare, Vercel, Docker, Kubernetes
  552. **Observability:** Grafana, Prometheus, Datadog, LangSmith, Langfuse, Arize
  553. ---
  554. ## Troubleshooting
  555. | Symptom | Cause | Fix |
  556. |---------|-------|-----|
  557. | PNG is blank or all-black | `@import url()` in SVG — neither cairosvg nor rsvg-convert can fetch external fonts | Remove `@import`, use system font stack |
  558. | PNG not generated | No renderer installed | `python3 -m pip install cairosvg` (recommended), or `brew install librsvg` / `apt install librsvg2-bin` |
  559. | Borders or text missing in PNG | Using `rsvg-convert` on SVG with CSS / `<foreignObject>` | Switch to `cairosvg` (`python3 -m pip install cairosvg`) — much better CSS support |
  560. | Diagram cut off at bottom | ViewBox height too short | Increase `height` in `viewBox="0 0 960 <height>"` |
  561. | Text overflowing boxes | Labels too long | Add `text-anchor="middle"` + `<clipPath>` or shorten label |
  562. | Icons not rendering | External CDN URL | Use inline SVG paths from `references/icons.md` |
  563. | Browser-generated SVG renders incorrectly | cairosvg / rsvg can't replay all CSS/JS-injected styles | Use `scripts/svg2png.js` as described in `references/png-export.md` |
  564. ---
  565. ## License
  566. MIT © 2025 fireworks-tech-graph contributors

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.