About this project

fireworks-tech-graph is an Agent Skill that runs unchanged in Codex and Claude Code. It converts natural-language descriptions (English or Chinese) into geometry-checked SVG diagrams, high-resolution PNG exports, validated SVG-to-GIF semantic motion, and a single offline interactive HTML file. Core capabilities - 12 visual styles: 11 generator-backed profiles plus one AI-authored style (Dark Luxury). Four engineering-first styles add executable contracts for C4 reviews, cloud deployments, event streams and reliability investigations. - 14 diagram types with full UML support: Class, Component, Deployment, Package, Composite Structure, Object, Use Case, Activity, State Machine, Sequence, Communication, Timing, Interaction Overview and ER Diagram, alongside AI/Agent domain patterns such as RAG, Agentic Search, Mem0, Multi-Agent and Tool Call. - Semantic vocabulary: shapes encode roles (LLM as double-border rectangle, Agent as hexagon, Vector Store as ringed cylinder) and arrow color/dash patterns encode meaning (write, read, async, loop). - Routing and layout: deterministic orthogonal routes with exact waypoints, distinct ports, automatic legend relocation, labels kept inside the canvas, and verified bridge jumps for unavoidable crossings. - Validation: a versioned diagram IR normalizes legacy JSON to schema v1 and fails on duplicate IDs, dangling references, malformed waypoints or non-finite geometry; structured SVG checks cover XML and marker integrity plus node, reserved-region, label, canvas, edge-overlap and edge-crossing conditions. - Output: SVG for editing and 1920px PNG for embedding; pure inline SVG with no external font fetching, intended to render in cairosvg, rsvg-convert and headless Chrome. A unified CLI supports render, validate, check, export-html and animate, and the HTML export adds pan/zoom, light/dark themes, source copy and SVG/PNG/JPEG/WebP downloads at 1x-4x. - Motion: the animate command accepts a generated semantic SVG carrying one of twelve approved motion contracts and emits a GIF plus a motion.json verification report. The documented default is 960px, 5.75 seconds, 20fps, 115 frame samples, with connectors drawn in semantic order; shorter 75-frame and 55-frame timelines are also supported. - Visual review gate: exported PNGs are inspected for clipping, overlap, label placement and routing regressions, with at most two focused correction passes by default; if the runtime cannot read images, the skill reports visual_review as skipped rather than claiming verification. - Product icons: 40+ products with brand colors, plus automatic swim-lane grouping for complex architectures. Installation and requirements Installation is via the skills CLI using the nested path skills/fireworks-tech-graph, or by cloning the repository into ~/.agents/skills (Codex) or ~/.claude/skills (Claude Code); a shared checkout with symlinks is also documented. Python 3.9+ is required. SVG/PNG scripts need cairosvg (recommended) or rsvg-convert; optional GIF export needs FFmpeg/FFprobe, Chrome/Chromium and puppeteer or puppeteer-core, with Node.js 22.12+ for the Puppeteer path. The README positions the project against Mermaid and draw.io, noting that it accepts natural-language input, includes AI/Agent domain patterns, ships built-in styles, exports high-resolution PNG automatically and needs no online tool. It is released under the MIT license.