# fireworks-tech-graph

> Generate publication-ready SVG, PNG, and animated GIF technical diagrams from natural language descriptions, with 12 visual styles and built-in AI/Agent domain patterns.

fireworks-tech-graph is an open-source agent skill that turns plain English or Chinese descriptions into polished, geometry-checked technical diagrams — outputting SVG, high-resolution PNG, and validated animated GIFs. It runs unchanged inside both OpenAI Codex and Anthropic Claude Code, and is published under the MIT license. The project reached v1.2.0 with a verified semantic SVG-to-GIF motion runtime shared across all twelve visual styles.

## What It Is

fireworks-tech-graph is a diagram-generation skill for AI coding agents. Instead of writing Mermaid DSL or clicking through draw.io, a developer describes a system in natural language — "Draw a Mem0 memory architecture, dark style" — and the skill classifies the diagram type, generates a geometry-safe SVG, exports a 1920px PNG, and optionally produces an animated GIF with draw-on connector animation and persistent data flow. The skill ships with 12 distinct visual styles, 14 UML diagram types, and built-in pattern knowledge for AI/Agent architectures including RAG, Agentic RAG, Mem0, Multi-Agent, and Tool Call flows.

## How the Skill Works

The generation pipeline follows a bounded, agent-driven validation loop rather than treating the first render as final:

- **Natural language in** — trigger phrases like "draw a diagram", "visualize", "architecture diagram", or Chinese equivalents (画图 / 帮我画) auto-classify the diagram type and style.
- **Semantic IR** — typed nodes and edges are normalized to a versioned schema; duplicate IDs, dangling references, and malformed waypoints fail before rendering.
- **Geometry-safe routing** — deterministic orthogonal routes, exact waypoints, distinct port fan-out, label and legend avoidance, and verified bridge jumps keep wires out of boxes.
- **Structured SVG validation** — XML and marker integrity, semantic node checks, reserved-region, canvas, edge-overlap, and edge-crossing checks run before export.
- **PNG visual readback** — exported PNGs are inspected for clipping, overlap, label placement, and routing regressions before delivery.
- **Targeted correction** — each pass changes only diagnosed coordinates or spacing, then reruns validation; at most two focused correction passes are allowed by default.

## Twelve Visual Styles and Motion

Styles 1–7 and 9–12 are deterministic generator-backed profiles; Style 8 (Dark Luxury) is AI-authored with a static regression fixture. Every style shares one approved motion contract: connectors begin absent, draw in on frames 1–36, fade to live flow on frames 36–38, hold full settled flow on frames 38–109, and reset on frames 110–114 — producing a 5.75-second, 20fps, 115-frame infinite loop at 960px wide. Style highlights include:

- **Flat Icon** (default) — white background, colored accents, suited for blogs and slides
- **Dark Terminal** — dark background, monospace fonts, ideal for GitHub READMEs
- **Blueprint** — engineering grid, cyan lines, for architecture docs
- **Glassmorphism** — frosted glass cards on dark gradient, for product sites and keynotes
- **C4 Review Canvas** — enforces one declared C4 abstraction level with responsibilities and protocols
- **Ops Pulse** — golden signals, one critical path, OTel export, and a correlated trace

## AI/Agent Domain Patterns and Shape Vocabulary

The skill encodes semantic meaning into shapes consistently across all styles: LLMs use double-border rounded rectangles, Agents use hexagons, Vector Stores use ringed cylinders, and Queues use horizontal pipes. Arrow stroke and dash patterns encode flow type — solid for primary data flow, dashed for memory writes, and curved for feedback loops. Built-in pattern knowledge covers RAG Pipeline, Agentic RAG, Agentic Search, Mem0 Memory Layer, Agent Memory Types, Multi-Agent, and Tool Call Flow. Over 40 brand icons ship as inline SVG with correct brand colors — covering OpenAI, Anthropic, Pinecone, Weaviate, Kafka, LangChain, LangGraph, CrewAI, Kubernetes, and Grafana, among others.

## Update: v1.2.0 — Semantic SVG→GIF Motion Live

Version 1.2.0, published July 2026, is the current release. The headline change is a unified, fail-closed SVG-to-GIF motion runtime applied to all twelve styles. The runtime validates draw-on sequence, settled data flow, the 5.75-second timeline, frame cadence, and infinite looping before atomically installing the final GIF artifact. The project reports 9,587 GitHub stars and 802 forks as of the last metadata update.

## Setup Path

Install via the `skills` CLI into Codex and Claude Code simultaneously:

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

Alternatively, clone the repository directly into `~/.agents/skills/` for Codex or `~/.claude/skills/` for Claude Code. PNG export requires `cairosvg` (recommended) or `rsvg-convert`; animated GIF export additionally requires FFmpeg, Chrome/Chromium, and Puppeteer. Python 3.9+ is required; the optional Puppeteer path requires Node.js 18+.

## Features
- Natural language diagram generation in English and Chinese
- 12 distinct visual styles (11 generator-backed + 1 AI-authored Dark Luxury)
- 14 UML diagram types including Class, Sequence, State Machine, ER Diagram, and more
- Built-in AI/Agent domain patterns: RAG, Agentic RAG, Mem0, Multi-Agent, Tool Call Flow
- Semantic shape vocabulary: hexagons for Agents, ringed cylinders for Vector Stores, double-border rects for LLMs
- Geometry-safe orthogonal routing with exact waypoints, port fan-out, and verified bridge jumps
- Structured SVG validation: XML integrity, marker checks, edge-overlap and edge-crossing detection
- PNG visual readback gate for clipping, overlap, label placement, and routing regressions
- Validated SVG-to-GIF semantic motion: draw-on connectors + persistent settled data flow
- 5.75-second, 20fps, 115-frame infinite loop GIF at 960px wide
- 40+ brand icons as inline SVG with correct brand colors (no CDN fetch)
- Swim lane grouping with automatic layer labeling
- 1920px high-resolution PNG export
- Offline interactive HTML export with pan/zoom, themes, and multi-format download
- Unified CLI: validate, render, check, animate, export-html, doctor
- Versioned diagram IR with schema normalization and fail-closed validation
- Engineering semantic contracts for C4 reviews, cloud deployments, event streams, and reliability
- Bounded agent-driven validation feedback loop with at most two correction passes
- Supports cairosvg, rsvg-convert, and headless Chrome/Puppeteer renderers
- Works unchanged in both OpenAI Codex and Anthropic Claude Code

## Integrations
OpenAI Codex, Anthropic Claude Code, cairosvg, rsvg-convert, Puppeteer / puppeteer-core, FFmpeg, Chrome / Chromium, ImageMagick, npm / npx skills CLI, Python 3.9+, Node.js 18+

## Platforms
WINDOWS, MACOS, LINUX, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v1.2.0

## Links
- Website: https://yizhiyanhua-ai.github.io/fireworks-tech-graph/
- Documentation: https://github.com/yizhiyanhua-ai/fireworks-tech-graph#readme
- Repository: https://github.com/yizhiyanhua-ai/fireworks-tech-graph
- EveryDev.ai: https://www.everydev.ai/tools/fireworks-tech-graph