sfguide-diagram

sfguide-diagram

Builds assets/architecture-diagram.png for an sfguide from a small Python script that stays in the repo (assets/architecture_diagram.py), so the diagram can be regenerated after edits.

The template at scripts/architecture_diagram.py is complete and tested. Copy it, then edit only the STYLE, NODES, and EDGES data and the figure limits. Do not rewrite the layout code.

What the template guarantees

• Square-cornered boxes sized to their text, with equal padding (PAD_PX) on all four sides; bold title over a smaller subtitle.
• Arrows clipped to box borders; rad gives a curved edge (use it to route around boxes).
• Edge labels rotated to the arrow's direction, never upside down, placed beside the line with the same visible gap on both sides (descender-corrected).
• Labels keep LINE_CLEAR_PX from every other line and LABEL_CLEAR_PX from boxes and other labels. If no clear spot exists, the script prints warning: label ... could not be placed cleanly.
• Legend centered below the diagram, listing only object types that appear.

Workflow

1. Read the guide. Find the .md under the guide folder. List every Snowflake object the guide creates (tables, warehouses, procedures, tasks, services, Streamlit apps, stages, dynamic tables, agents, and so on) and every interaction between them (writes, reads, calls, schedules, polls). Note the SQL verb or action for each interaction; it becomes the edge label.
2. Confirm the inventory with the user in a short list (objects and edges) when the guide is ambiguous. Skip if it is clear.
3. Copy the template to <guide>/assets/architecture_diagram.py.
4. Fill the data:
   • STYLE: one entry per object type, (fill, edge) colors. Reuse the existing palette; add types with a light fill and darker edge.
   • NODES: key: (x, y, type, TITLE, "subtitle"). Use the real object names in caps as titles, and a short role as subtitle (use \n for two lines). Lay out on a grid, left to right in data-flow order, about 5 units between columns and 2.5 between rows.
   • EDGES: (src, dst, "label", color, dashed, rad). Color the edge with the edge color of the type doing the action. Dashed for control/config/fallback flows, solid for data flow. Keep labels to 1-3 words; use \n for two lines.
   • Set figsize, xlim, ylim so the grid fits with a small margin.
5. Render: cd <guide>/assets && python3 architecture_diagram.py. Read the PNG to check it.
6. Fix problems by moving data, not code:
   • Warning printed, or labels crowded: move nodes apart, or give a crossing edge a rad (0.15 to 0.3) to bend it away.
   • Edge crosses a box: add rad or move one node.
   • Too much whitespace: tighten xlim/ylim.
   • Wanting more breathing room: raise LABEL_GAP_PX (all line gaps follow it) or PAD_PX.
7. Wire it into the guide: reference assets/architecture-diagram.png with alt text, and add an HTML comment next to the image noting that it is generated by architecture_diagram.py. Remove any old .excalidraw source with git rm.

Examples

Prompt: Create an architecture diagram for the sfguide in this folder.

Output: assets/architecture_diagram.py with NODES and EDGES filled from the guide, plus the rendered assets/architecture-diagram.png. A minimal data block:

NODES = {
    "sp":     (2.0, 4.0, "Stored Procedure", "SP_LOAD", "Writes each tick"),
    "orders": (7.0, 4.0, "Table", "ORDERS", "Latest snapshot"),
    "dash":   (12.0, 4.0, "Streamlit in Snowflake", "DASHBOARD", "Live charts"),
}
EDGES = [
    ("sp", "orders", "INSERT\nOVERWRITE", "#C2185B", False, 0.0),
    ("orders", "dash", "SELECT", "#0097A7", False, 0.0),
]

Notes

• Requires only matplotlib (see pyproject.toml). If it is not installed, run uv run --with matplotlib python architecture_diagram.py. Do not add dependencies.
• Keep LINE_CLEAR_PX equal to LABEL_GAP_PX so every label has the same margin from every line.
• Do not commit or push without asking the user.