Fireworks Tech Graph

Generate production-quality SVG technical diagrams exported as PNG via

rsvg-convert

Routing Rule (with image-gen)

• Use this skill when the request is a technical diagram that needs structured/editable SVG (architecture, sequence, swimlane, ER, state-machine, data flow).
• Use

  image-gen

  when the request is artistic, illustrative, photorealistic, or non-structured image generation.

Install Source

Install this skill from GitHub:

npx skills add yizhiyanhua-ai/fireworks-tech-graph

Public package page:

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

Do not pass

@yizhiyanhua-ai/fireworks-tech-graph

skills add

Update command:

npx skills add yizhiyanhua-ai/fireworks-tech-graph --force -g -y

Helper Scripts (Recommended)

Four helper scripts in

scripts/

1.

generate-diagram.sh

- Validate SVG + export PNG

./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg

• Validates an existing SVG file
• Exports PNG after validation
• Example:

  ./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg

2.

generate-from-template.py

- Create starter SVG from template

python3 ./scripts/generate-from-template.py architecture ./output/arch.svg '{"title":"My Diagram","nodes":[],"arrows":[]}'

• Loads a built-in SVG template
• Renders nodes, arrows, and legend entries from JSON input
• Escapes text content to keep output XML-valid

3.

validate-svg.sh

- Validate SVG syntax

./scripts/validate-svg.sh <svg-file>

• Checks XML syntax
• Verifies tag balance
• Validates marker references
• Checks attribute completeness
• Validates path data

4.

test-all-styles.sh

- Batch test all styles

./scripts/test-all-styles.sh

• Tests multiple diagram sizes
• Validates all generated SVGs
• Generates test report

When to use scripts:

• Use scripts when generating complex SVGs to avoid syntax errors
• Scripts provide automatic validation and error reporting
• Recommended for production diagrams

When to generate SVG directly:

• Simple diagrams with few elements
• Quick prototypes
• When you need full control over SVG structure

Workflow (Always Follow This Order)

1. Classify the diagram type (see Diagram Types below)
2. Extract structure — identify layers, nodes, edges, flows, and semantic groups from user description
3. Plan layout — apply the layout rules for the diagram type
4. Load style reference — always load

   references/style-1-flat-icon.md

   unless user specifies another; load the matching

   references/style-N.md

   for exact color tokens and SVG patterns
5. Map nodes to shapes — use Shape Vocabulary below
6. Check icon needs — load

   references/icons.md

   for known products
7. Write SVG with adaptive strategy (see SVG Generation Strategy below)
8. Validate: Run

   rsvg-convert file.svg -o /dev/null 2>&1

   to check syntax
9. Export PNG:

   rsvg-convert -w 1920 file.svg -o file.png

10. Report the generated file paths

Diagram Types & Layout Rules

Architecture Diagram

Nodes = services/components. Group into horizontal layers (top→bottom or left→right).

• Typical layers: Client → Gateway/LB → Services → Data/Storage
• Use

  <rect>

  dashed containers to group related services in the same layer
• Arrow direction follows data/request flow
• ViewBox:

  0 0 960 600

  standard,

  0 0 960 800

  for tall stacks

Data Flow Diagram

Emphasizes what data moves where. Focus on data transformation.

• Label every arrow with the data type (e.g., "embeddings", "query", "context")
• Use wider arrows (

  stroke-width: 2.5

  ) for primary data paths
• Dashed arrows for control/trigger flows
• Color arrows by data category (not just Agent/RAG — use semantics)

Flowchart / Process Flow

Sequential decision/process steps.

• Top-to-bottom preferred; left-to-right for wide flows
• Diamond shapes for decisions, rounded rects for processes, parallelograms for I/O
• Keep node labels short (≤3 words); put detail in sub-labels
• Align nodes on a grid: x positions snap to 120px intervals, y to 80px

Agent Architecture Diagram

Shows how an AI agent reasons, uses tools, and manages memory. Key conceptual layers to always consider:

• Input layer: User, query, trigger
• Agent core: LLM, reasoning loop, planner
• Memory layer: Short-term (context window), Long-term (vector/graph DB), Episodic
• Tool layer: Tool calls, APIs, search, code execution
• Output layer: Response, action, side-effects Use cyclic arrows (loop arcs) to show iterative reasoning. Separate memory types visually.

Memory Architecture Diagram (Mem0, MemGPT-style)

Specialized agent diagram focused on memory operations.

• Show memory write path and read path separately (different arrow colors)
• Memory tiers: Working Memory → Short-term → Long-term → External Store
• Label memory operations:

  store()

  ,

  retrieve()

  ,

  forget()

  ,

  consolidate()

• Use stacked rects or layered cylinders for storage tiers

Sequence Diagram

Time-ordered message exchanges between participants.

• Participants as vertical lifelines (top labels + vertical dashed lines)
• Messages as horizontal arrows between lifelines, top-to-bottom time order
• Activation boxes (thin filled rects on lifeline) show active processing
• Group with

  <rect>

  loop/alt frames with label in top-left corner
• ViewBox height = 80 + (num_messages × 50)

Comparison / Feature Matrix

Side-by-side comparison of approaches, systems, or components.

• Column headers = systems, row headers = attributes
• Row height: 40px; column width: min 120px; header row height: 50px
• Checked cell: tinted background (e.g.

  #dcfce7

  ) +

  ✓

  checkmark; unsupported:

  #f9fafb

  fill
• Alternating row fills (

  #f9fafb

  /

  #ffffff

  ) for readability
• Max readable columns: 5; beyond that, split into two diagrams

Timeline / Gantt

Horizontal time axis showing durations, phases, and milestones.

• X-axis = time (weeks/months/quarters); Y-axis = items/tasks/phases
• Bars: rounded rects, colored by category, labeled inside or beside
• Milestone markers: diamond or filled circle at specific x position with label above
• ViewBox:

  0 0 960 400

  typical; wider for many time periods:

  0 0 1200 400

Mind Map / Concept Map

Radial layout from central concept.

• Central node at

  cx=480, cy=280

• First-level branches: evenly distributed around center (360/N degrees)
• Second-level branches: branch off first-level at 30-45° offset
• Use curved

  <path>

  with cubic bezier for branches, not straight lines

Class Diagram (UML)

Static structure showing classes, attributes, methods, and relationships.

• Class box: 3-compartment rect (name / attributes / methods), min width 160px
  • Top compartment: class name, bold, centered (abstract = italic)
  • Middle: attributes with visibility (

    +

    public,

    -

    private,

    #

    protected)
  • Bottom: method signatures, same visibility notation
• Relationships:
  • Inheritance (extends): solid line + hollow triangle arrowhead, child → parent
  • Implementation (interface): dashed line + hollow triangle, class → interface
  • Association: solid line + open arrowhead, label with multiplicity (1, 0.., 1..)
  • Aggregation: solid line + hollow diamond on container side
  • Composition: solid line + filled diamond on container side
  • Dependency: dashed line + open arrowhead
• Interface:

  <<interface>>

  stereotype above name, or circle/lollipop notation
• Enum: compartment rect with

  <<enumeration>>

  stereotype, values in bottom
• Layout: parent classes top, children below; interfaces to the left/right of implementors
• ViewBox:

  0 0 960 600

  standard;

  0 0 960 800

  for deep hierarchies

Use Case Diagram (UML)

System functionality from user perspective.

• Actor: stick figure (circle head + body line) placed outside system boundary
  • Label below figure, 13-14px
  • Primary actors on left, secondary/supporting on right
• Use case: ellipse with label centered inside, min 140×60px
  • Keep names verb phrases: "Create Order", "Process Payment"
• System boundary: large rect with dashed border + system name in top-left
• Relationships:
  • Include: dashed arrow

    <<include>>

    from base to included use case
  • Extend: dashed arrow

    <<extend>>

    from extension to base use case
  • Generalization: solid line + hollow triangle (specialized → general)
• Layout: system boundary centered, actors outside, use cases inside
• ViewBox:

  0 0 960 600

  standard

State Machine Diagram (UML)

Lifecycle states and transitions of an entity.

• State: rounded rect with state name, min 120×50px
  • Internal activities: small text

    entry/ action

    ,

    exit/ action

    ,

    do/ activity

  • Initial state: filled black circle (r=8), one outgoing arrow
  • Final state: filled circle (r=8) inside hollow circle (r=12)
  • Choice: small hollow diamond, guard labels on outgoing arrows

    [condition]

• Transition: arrow with optional label

  event [guard] / action

  • Guard conditions in square brackets
  • Actions after

    /

• Composite/nested state: larger rect containing sub-states, with name tab
• Fork/join: thick horizontal or vertical black bar (synchronization)
• Layout: initial state top-left, final state bottom-right, flow top-to-bottom
• ViewBox:

  0 0 960 600

  standard

ER Diagram (Entity-Relationship)

Database schema and data relationships.

• Entity: rect with entity name in header (bold), attributes below
  • Primary key attribute: underlined
  • Foreign key: italic or marked with (FK)
  • Min width: 160px; attribute font-size: 12px
• Relationship: diamond shape on connecting line
  • Label inside diamond: "has", "belongs to", "enrolls in"
  • Cardinality labels near entity:

    1

    ,

    N

    ,

    0..1

    ,

    0..*

    ,

    1..*

• Weak entity: double-bordered rect with double diamond relationship
• Associative entity: diamond + rect hybrid (rect with diamond inside)
• Line style: solid for identifying relationships, dashed for non-identifying
• Layout: entities in 2-3 rows, relationships between related entities
• ViewBox:

  0 0 960 600

  standard; wider

  0 0 1200 600

  for many entities

Network Topology

Physical or logical network infrastructure.

• Devices: icon-like rects or rounded rects
  • Router: circle with cross arrows
  • Switch: rect with arrow grid
  • Server: stacked rect (rack icon)
  • Firewall: brick-pattern rect or shield shape
  • Load Balancer: horizontal split rect with arrows
  • Cloud: cloud path (overlapping arcs)
• Connections: lines between device centers
  • Ethernet/wired: solid line, label bandwidth
  • Wireless: dashed line with WiFi symbol
  • VPN: dashed line with lock icon
• Subnets/Zones: dashed rect containers with zone label (DMZ, Internal, External)
• Labels: device hostname + IP below, 12-13px
• Layout: tiered top-to-bottom (Internet → Edge → Core → Access → Endpoints)
• ViewBox:

  0 0 960 600

  standard

UML Coverage Map

Full mapping of UML 14 diagram types to supported diagram types:

Shape Vocabulary

Map semantic concepts to consistent shapes across all diagram types:

Arrow Semantics

Always assign arrow meaning, not just color:

#2563eb

#ea580c

#059669

#059669

5,3

#6b7280

4,2

#7c3aed

#7c3aed

Always include a legend when 2+ arrow types are used.

Layout Rules & Validation

Spacing:

• Same-layer nodes: 80px horizontal, 120px vertical between layers
• Canvas margins: 40px minimum, 60px between node edges
• Snap to 8px grid: horizontal 120px intervals, vertical 120px intervals

Arrow Labels (CRITICAL):

• MUST have background rect:

  <rect fill="canvas_bg" opacity="0.95"/>

  with 4px horizontal, 2px vertical padding
• Place mid-arrow, ≤3 words, stagger by 15-20px when multiple arrows converge
• Maintain 10px safety distance from nodes

Arrow Routing:

• Prefer orthogonal (L-shaped) paths to minimize crossings
• Anchor arrows on component edges, not geometric centers
• Route around dense node clusters, use different y-offsets for parallel arrows
• Jump-over arcs (5px radius) for unavoidable crossings

Line Overlap Prevention (CRITICAL - most common bug on Codex): When two arrows must cross each other, ALWAYS use jump-over arcs to prevent visual overlap:

• Crossing horizontal arrows: add a small semicircle arc (radius 5px, stroke same color as arrow, fill none) that "jumps over" the other line
• SVG pattern for jump-over: use a white/matching-background arc on the lower layer, then draw the upper arc on top
• Multiple crossings: stagger arc radii (5px, 7px, 9px) so arcs don't overlap each other
• Never let two arrows' straight-line segments cross without a jump-over arc

Validation Checklist (run before finalizing):

1. Arrow-Component Collision: Arrows MUST NOT pass through component interiors (route around with orthogonal paths)
2. Text Overflow: All text MUST fit with 8px padding (estimate:

   text.length × 7px ≤ shape_width - 16px

   )
3. Arrow-Text Alignment: Arrow endpoints MUST connect to shape edges (not floating); all arrow labels MUST have background rects
4. Container Discipline: Prefer arrows entering and leaving section containers through open gaps between components, not through inner component bodies

SVG Technical Rules

• ViewBox:

  0 0 960 600

  default;

  0 0 960 800

  tall;

  0 0 1200 600

  wide
• Fonts: embed via

  <style>font-family: ...</style>

  — no external

  @import

  (breaks rsvg-convert)

• <defs>

  : arrow markers, gradients, filters, clip paths
• Text: minimum 12px, prefer 13-14px labels, 11px sub-labels, 16-18px titles
• All arrows:

  <marker>

  with

  markerEnd

  , sized

  markerWidth="10" markerHeight="7"

• Drop shadows:

  <feDropShadow>

  in

  <filter>

  , apply sparingly (key nodes only)
• Curved paths: use

  M x1,y1 C cx1,cy1 cx2,cy2 x2,y2

  cubic bezier for loops/feedback arrows
• Clip content: use

  <clipPath>

  if text might overflow a node box

SVG Generation & Error Prevention

MANDATORY: Python List Method (ALWAYS use this):

python3 << 'EOF'
lines = []
lines.append('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 700">')
lines.append('  <defs>')
# ... each line separately
lines.append('</svg>')

with open('/path/to/output.svg', 'w') as f:
    f.write('\n'.join(lines))
print("SVG generated successfully")
EOF

Why mandatory: Prevents character truncation, typos, and syntax errors. Each line is independent and easy to verify.

Pre-Tool-Call Checklist (CRITICAL - use EVERY time):

1. ✅ Can I write out the COMPLETE command/content right now?
2. ✅ Do I have ALL required parameters ready?
3. ✅ Have I checked for syntax errors in my prepared content?

If ANY answer is NO: STOP. Do NOT call the tool. Prepare the content first.

Error Recovery Protocol:

• First error: Analyze root cause, apply targeted fix
• Second error: Switch method entirely (Python list → chunked generation)
• Third error: STOP and report to user - do NOT loop endlessly
• Never: Retry the same failing command or call tools with empty parameters

Validation (run after generation):

rsvg-convert file.svg -o /tmp/test.png 2>&1 && echo "✓ Valid" && rm /tmp/test.png

If using

generate-from-template.py

• Prefer

  source

  /

  target

  node ids in arrow JSON so the generator can snap to node edges
• Keep

  x1,y1,x2,y2

  as hints or fallback coordinates, not the main routing primitive
• Let the generator choose orthogonal routes; avoid hardcoding center-to-center straight lines unless the path is guaranteed clear

Common Syntax Errors to Avoid:

• ❌

  yt-anchor

  → ✅

  y="60" text-anchor="middle"

• ❌

  x="390

  (missing y) → ✅

  x="390" y="250"

• ❌

  fill=#fff

  → ✅

  fill="#ffffff"

• ❌

  marker-end=

  → ✅

  marker-end="url(#arrow)"

• ❌

  L 29450

  → ✅

  L 290,220

• ❌ Missing

  </svg>

  at end

Output

• Default:

  ./[derived-name].svg

  and

  ./[derived-name].png

  in current directory
• Custom: user specifies path with

  --output /path/

  or

  输出到 /path/

• PNG export:

  rsvg-convert -w 1920 file.svg -o file.png

  (1920px = 2x retina)

Styles

#0f0f1a

#0a1628

#f8f6f3

#ffffff

Load

references/style-N.md

Style Selection

Default: Style 1 (Flat Icon) for most diagrams. Load

references/style-diagram-matrix.md

These patterns appear frequently — internalize them:

RAG Pipeline: Query → Embed → VectorSearch → Retrieve → Augment → LLM → Response Agentic RAG: adds Agent loop with Tool use between Query and LLM Agentic Search: Query → Planner → [Search Tool / Calculator / Code] → Synthesizer → Response Mem0 / Memory Layer: Input → Memory Manager → [Write: VectorDB + GraphDB] / [Read: Retrieve+Rank] → Context Agent Memory Types: Sensory (raw input) → Working (context window) → Episodic (past interactions) → Semantic (facts) → Procedural (skills) Multi-Agent: Orchestrator → [SubAgent A / SubAgent B / SubAgent C] → Aggregator → Output Tool Call Flow: LLM → Tool Selector → Tool Execution → Result Parser → LLM (loop)