AGENT SKILL

mermaid-infra-diagram

Generate a control's 'Demo infrastructure setup (simplified)' diagram with real Microsoft/Azure service icons instead of abstract colored boxes. Primary path: draw.io XML rendered headlessly via the bundled VS Code draw.io extension, using the official Azure Public Service Icons set indexed at media/icons/Azure_Public_Service_Icons/icon-index.jsonl. Fallback path: Mermaid architecture-beta with Iconify icon packs, pre-rendered because GitHub does not render Mermaid icon packs live. For controls that deploy Azure resources, follow the KNW-001 reference layout: nested subscription, resource group and resource boundaries, a legend, an outside-scope band and tiered icon sizes. Use when creating or refreshing a control's Demo infrastructure setup (simplified) section, or when a plain flowchart diagram should show recognizable real-world service icons instead of abstract colored boxes.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 2
Forks
1

01 前言 Front Matter

name
mermaid-infra-diagram
license
MIT
metadata
{ "authors": "Douwe van de Ruit", "spec_version": "2.0" }
description
Generate a control's 'Demo infrastructure setup (simplified)' diagram with real Microsoft/Azure service icons instead of abstract colored boxes. Primary path: draw.io XML rendered headlessly via the bundled VS Code draw.io extension, using the official Azure Public Service Icons set indexed at media/icons/Azure_Public_Service_Icons/icon-index.jsonl. Fallback path: Mermaid architecture-beta with Iconify icon packs, pre-rendered because GitHub does not render Mermaid icon packs live. For controls that deploy Azure resources, follow the KNW-001 reference layout: nested subscription, resource group and resource boundaries, a legend, an outside-scope band and tiered icon sizes. Use when creating or refreshing a control's Demo infrastructure setup (simplified) section, or when a plain flowchart diagram should show recognizable real-world service icons instead of abstract colored boxes.
user-invocable
true

03 SKILL.md 正文

Demo infrastructure setup (simplified) diagram with real icons

Why this exists, and the one hard constraint to respect

Most controls' "Demo infrastructure setup (simplified)" sections in this repository use a plain Mermaid flowchart with classDef-based color coding (purple/blue/green/orange) instead of real service icons, because that is what GitHub's built-in Mermaid renderer supports natively in a live code block. Two controls use this skill's icon-based pipeline (docs/architecture.drawio + media/architecture.png):

  • KNW-001_knowledge_freshness_breach -- the preferred reference. Its Azure-scope layout (see "Reference layout" below) was confirmed by the user on 2026-11-08 as clearly better than the earlier style. Copy its .drawio as the starting point for any control that deploys Azure resources.
  • QLT-001_hallucination_rate_high -- the earlier free-floating icon chain. It is still a valid example of a causal chain with no deployed resource boundary to show, but don't copy its group or icon-size conventions into a new diagram.

Whichever tool builds the diagram, GitHub cannot render it live: it does not call Mermaid's registerIconPacks() for architecture-beta icons, and it has no draw.io renderer at all for .drawio XML. Either way the only option is to pre-render the diagram locally to a static PNG and commit that image -- the same "capture once, commit the artifact" pattern this repository already uses for screenshots (scripts/capture_teams_card.py). This means an icon-based architecture diagram is not a live-editable code block like this repository's other diagrams: every future edit requires re-running the render step and re-committing the image. Say this trade-off out loud to the user before switching a control over, and keep the diagram source file (.drawio or .mmd) committed alongside the image so it can be re-rendered.

When to use

  • Creating a new control's "Demo infrastructure setup (simplified)" section and real Azure/Microsoft/GitHub/Python service icons would make the building blocks easier to recognize than colored boxes.
  • The user asks to add or refresh real icons on an existing control's architecture diagram.
  • Do not use this for "Logical design" diagrams (decision flow, not building blocks) -- keep those as plain flowchart code blocks per .github/instructions/governance-controls.instructions.md.

Which tool: draw.io (preferred) or Mermaid (fallback)

Use draw.io (scripts/render_drawio_diagram.py) unless the VS Code "Draw.io Integration" extension (hediet.vscode-drawio) is not installed on this machine. It is the better fit for this repository specifically because media/icons/Azure_Public_Service_Icons/ already holds the official, Microsoft-published Azure Public Service Icons set (714 SVGs across ~29 categories) with a prebuilt search index -- draw.io just needs a relative path to one of those files, no icon-pack build step, no CORS server, and free-form pixel-precise layout instead of Mermaid's architecture-beta auto-layout (which produced label/icon overlap and awkward spacing on earlier attempts).

Fall back to Mermaid (scripts/render_architecture_diagram.py, see "Mermaid fallback" below) only when the draw.io extension genuinely is not available and installing it is not an option -- it needs its own local Iconify icon-pack build step and a CORS-enabled local server for any official custom icon, which is more moving parts for the same result.

Reference layout: Azure scope boundaries (preferred)

Confirmed on KNW-001 (2026-11-08). The user compared it with that control's earlier diagram (free-floating icons, dashed "NOT DEPLOYED"/"pending" boxes and edges, a "Remaining integrations" column) and called the new version clearly better. Use this layout whenever a control deploys or configures Azure resources. Open controls/data_and_knowledge/KNW-001_knowledge_freshness_breach/docs/architecture.drawio and copy its cells rather than restyling from scratch.

Why it works: a reader can match each box one to one with what they will see in the Azure Portal after deployment (subscription, then resource group, then resource, then sub-resource). It shows only what the demo actually deploys. Every arrow means the same thing (the caller calls the service the arrow points to), and the legend says so.

Canvas layout, top to bottom:

  1. Title and subtitle, top-left. The title is <ID> · <control name> — demo infrastructure (fontSize=19;fontStyle=1;fontColor=#182B39). The subtitle is italic gray (fontSize=12;fontStyle=2;fontColor=#555555), for example "Synthetic data only. Arrows point from the caller to the service it calls."
  2. Legend box, top-right (fillColor=#FFFFFF;strokeColor=#7F7F7F, rounded=1;arcSize=4;absoluteArcSize=1). It has one short sample line per edge kind (for example "Data access (Entra ID)" and "Notification (HTTPS)") and one sample box per boundary meaning (for example "Deployed for the demo; removed by cleanup"). Every edge colour and boundary style in the diagram must appear in the legend, and nothing else should.
  3. Subscription boundary: a square-cornered rectangle with fillColor=#CFE2F7;strokeColor=#9DBFE6, plus a header tab above its top-left corner. The tab is a fillColor=#1F4E8C;strokeColor=none rectangle with a white bold text cell on top reading "Azure subscription (demo)".
  4. Resource group panel inside it (fillColor=#FAFAFA;strokeColor=#A6A6A6, arcSize=4 absolute). Its header is the Resource Groups icon (28px) followed by one text line: Resource group <b>rg-…-demo</b> · <region> · every resource tagged <i>control-id=<ID></i>. This turns the tagging convention from copilot-instructions.md into something visible.
  5. One white panel per resource or capability (fillColor=#FFFFFF;strokeColor=#BFBFBF or #7F7F7F, arcSize=4 absolute). Lay them out on a grid with equal gutters (20px in KNW-001). Each panel header is a 32-40px icon plus a two-line label: <b>Resource type</b><br><i>SKU · region</i>.
  6. Sub-resources inside a panel, such as Blob containers, go in an inner tinted panel (fillColor=#F4F7FB;strokeColor=#BFBFBF) with a small italic caption ("Blob containers"). Use one 30px icon plus a <b>name</b><br><i>purpose</i> label per item. Show sub-resources only when the control reads or writes them separately.
  7. Function apps: one card per function, not one icon per app. Use a 120x72 card (strokeColor=#E8B53A;strokeWidth=1.5;fillColor=#FFFFFF, arcSize=6 absolute) with a 28px Functions icon centered at the top and the label <b>Function name</b><br><i>trigger · auth</i> below it. Put the app's own header (icon + <b>Function App</b><br><i>plan · runtime</i>) at the bottom-left of the panel. That way edges leave from the specific function that makes the call.
  8. Identity and RBAC panel (only when the control relies on a managed identity): show the managed identity (<i>system-assigned · no stored secrets</i>) and one "RBAC role assignments" row listing the actual role names. Draw this as a passive panel with no edges. The legend's "Data access (Entra ID)" entry already explains how the calls authenticate. This narrows step 1's "leave auth out of the diagram" rule rather than contradicting it: no authenticates via edges or auth nodes, but a least-privilege access model the README's "Inspect in Azure" asks the reader to verify does belong on the diagram.
  9. Outside-scope band below the subscription, for anything the control uses but does not own or delete, such as Microsoft Entra ID and external notification sinks (Teams, HTTPS endpoints). Use a fillColor=#FFF8E1;strokeColor=#F2B705;strokeWidth=3 rectangle with a corner tag at its bottom-right (fillColor=#F9D86B, bold right-aligned text "Outside the control's resource group"). Write "(optional)" in the label of anything that is optional.
  10. Human actors (for example the Data Owner) stand outside every boundary, usually on the left. Use the Azure "Users" icon with a bold role name under it, and put their action on the edge label ("signs in, confirms the shown revision").

Icon sizes by tier, not one size for everything. Inside one tier, keep every icon the same size. Between tiers, size icons by role:

Tier Size Examples
Primary service or actor 48px Azure AI Search, Foundry agent, model deployment, Entra ID, Teams, a human actor
Resource panel header 32-40px Storage account, Foundry project, Function App, managed identity, RBAC
Small header badge or sub-resource 28-30px Resource Groups badge, Blob containers, per-function icon in a card

This replaces the older "every icon, badges included, at 64x64" rule. That rule fit a flat chain of four nodes, but in a nested layout the hierarchy is what makes it readable. Keep the "visual weight" check from "Verify icon sizing" below: a thin ribbon-style logo can still look smaller than a solid icon in the same tier.

Edges: two kinds, both solid, directed caller to callee.

  • Near-black data access: strokeColor=#1A1A1A;strokeWidth=1.5;endArrow=block;endFill=1;endSize=7.
  • Teal notification: the same style with strokeColor=#00A3BF, and a teal label.

Use edgeStyle=orthogonalEdgeStyle;rounded=0 with pinned exitX/exitY/entryX/entryY on every edge (see "Route edges deliberately"). Write labels as short verb phrases from the caller's side ("reads source metadata, writes evidence", "retrieves via project connection", "calls"). Put a schedule or other qualifier in italics on a second line ("Blob indexer<br><i>(24-hour schedule)</i>").

Match the label backdrop to the panel it sits on. The two-cell label pattern (see "Differentiate edges by meaning") still applies, but the backdrop rectangle's fillColor must equal the fill of the panel under it: #FAFAFA on the resource-group panel, #FFFFFF on a white resource panel. A white backdrop on the light-gray resource-group fill shows up as a visible white patch.

Show only what is deployed. Do not draw planned, pending, or "NOT DEPLOYED" components with dashed boxes and edges. The earlier KNW-001 diagram did this, and it made the picture about project status instead of the control. Status belongs in the README status line and docs/VALIDATION.md. Until a component exists, leave it out of the diagram, or mark it "(optional)" if it really is optional.

Size and embedding. KNW-001's canvas is about 1340 x 770 and is embedded at width="1100" after resizing. The alt text should list every boundary and component in reading order, so the image's content is available without seeing it.

draw.io workflow (preferred)

One-time setup (author-only, per machine)

Install the "Draw.io Integration" VS Code extension (hediet.vscode-drawio, marketplace id hediet.vscode-drawio) if it is not already present. Nothing else to install: scripts/render_drawio_diagram.py drives the extension's own bundled copy of the diagrams.net web app with Playwright (already a repository dependency via capture_teams_card.py), serving it over a throwaway local HTTP server (it needs http://, not file://, for its own internal resource fetches) and reusing the system Chrome via --channel chrome by default.

Steps

  1. Decide what belongs in the diagram before listing building blocks. Default to showing the core mechanism -- what a first-time reader needs to understand why this control works -- not every plumbing detail of how it happens to be run today. Confirmed the hard way on QLT-001 (2026-09-24), across several rounds of feedback: an early version made authentication (az/azd auth login) and the execution environment ("Local developer workstation (not an Azure resource)") into the most visually prominent nodes, each with its own box, badge, and long connecting line -- and the reviewer's reaction was that authentication "is not really the key thing to show here," and that naming the exact current execution environment "feels cumbersome" for a detail that could change (it could just as well be an Azure Function tomorrow). The fix that stuck: cut auth and the execution environment out of the diagram entirely and cover them in one prose sentence above the image instead (for example "This control's infrastructure is minimal: demo.py, run locally and authenticated via az/azd auth login, orchestrates every step below against an already-deployed Foundry project") -- then draw only the causal chain that explains the control's actual mechanism (a hosted agent's output is scored, the score becomes a decision, a breaching decision notifies someone). Treat "does every node in this diagram help someone understand why this control works, or does it just describe today's deployment convenience" as the filter, and default to prose for anything that fails it. A hosting detail earns a diagram node only when it is itself the notable fact (for example, a control whose whole point is a specific network boundary or managed identity). For a DEPLOYABLE_DEMO or HYBRID_DEMO with an "Inspect in Azure" section, the deployed resources and their scope are the notable fact. Show them with the "Reference layout" above, but still leave out deployment tooling (az, azd, the operator's workstation).

  2. List the real building blocks that survive that filter: the hosted agent/service, the platform capability that provides its signal, the component that turns the signal into a decision, and any external destination (Teams, GitHub Actions).

  3. Differentiate from this control's "Logical design" section. Every control README already has a "Logical design" Mermaid flowchart showing the decision branches (which threshold produces which outcome). Demo infrastructure setup (simplified) should not redraw the same branches with icons instead of colored boxes -- that is pure duplication with no new information. Show the building blocks and the data flow between them instead (what calls what, what artifact produces what), and say so explicitly in the prose above the image so the two sections' distinct jobs are legible to the reader, not just to whoever designed them (for example: "This is a different view from 'Logical design' above, not a repeat of it: Logical design shows the three decision branches; this diagram shows the building blocks and data flow that produce the score those branches decide on").

  4. Find a real icon for each node by searching the index instead of guessing a filename:

    grep -i "foundry agent" media/icons/Azure_Public_Service_Icons/icon-index.jsonl
    

    Each match is one JSON object with a path (relative to media/icons/Azure_Public_Service_Icons/Icons/), category, name, and slug. Prefer the most specific official match over a generic one -- confirmed the hard way on QLT-001 (2026-09-24): this set has precise icons like "Foundry Agent Service" and "Foundry Project", which are a real, correct match for a Foundry hosted agent and its containing project, not a stand-in. Re-run scripts/index_azure_icons.py if the icon set folder has been updated and the index looks stale (it is deterministic and diffable, so a re-run's diff shows exactly what changed). For anything that is not an Azure service at all (a local Python script, Microsoft Teams, another non-Azure product), do not force an Azure icon onto it. Check media/icons/ (repo root) for an existing real asset first; if none exists but the official brand SVG is already cached locally in .tooling/mermaid/node_modules/@iconify-json/logos/icons.json (installed for the Mermaid fallback below, but its icons are legitimate official brand SVGs regardless of which renderer uses them), extract it into a standalone file once:

    python3 -c "
    import json
    with open('.tooling/mermaid/node_modules/@iconify-json/logos/icons.json') as f:
        d = json.load(f)
    icon = d['icons']['python']  # or 'microsoft-teams', etc.
    w, h = icon.get('width', d['width']), icon.get('height', d['height'])
    open('media/icons/python-language.svg', 'w').write(
        f'<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{w}\" height=\"{h}\" viewBox=\"0 0 {w} {h}\">{icon[\"body\"]}</svg>'
    )"
    

    (an iconify pack entry is just an inner <body> fragment, not a standalone file -- it must be wrapped in a real <svg> root before icon: placeholder expansion or build_icon_pack.py can use it). Only if no real asset exists anywhere should a node fall back to a plain labeled box with no icon.

  5. Write the .drawio source (an <mxfile> containing one <diagram> with a plain <mxGraphModel>) in the control's own directory, for example docs/architecture.drawio. Reference each icon with an icon:<relative-path> placeholder in a shape=image style -- the render script resolves this to a real embedded image, you never write a raw data: URI by hand:

    <mxCell id="agent" value="Hosted agent"
            style="shape=image;image=icon:../../../../media/icons/Azure_Public_Service_Icons/Icons/ai + machine learning/038470523-icon-service-Foundry-Agent-Service.svg;verticalLabelPosition=bottom;verticalAlign=top;fontSize=12;labelBackgroundColor=#ffffff;"
            vertex="1" parent="1">
      <mxGeometry x="608" y="110" width="64" height="64" as="geometry" />
    </mxCell>
    

    The path is relative to the .drawio file's own directory. Use a plain rounded rectangle with a real icon (shape=image as above) for anything with an official match, and only fall back to a plain style="rounded=1;whiteSpace=wrap;html=1;fillColor=#EEF2FF;strokeColor=#6E56CF;fontSize=12;" box when nothing fits -- confirmed on QLT-001 (2026-09-24) that swapping plain boxes for real per-node icons (the Microsoft Teams logo for a "Teams Workflows" node, the Python logo for each Python script node) made the rendered diagram noticeably more compelling than text-only boxes, even where no Azure-specific icon exists.

    For a control that deploys Azure resources, use the nested Azure-scope boundaries from "Reference layout" above instead of the dashed tinted groups and uniform 64x64 icons described in the rest of this paragraph. The rest of this paragraph still applies to a flat causal chain with no deployed resource boundary (the QLT-001 shape).

    Draw a dashed rounded rectangle with a light fill tint (fillColor=#F5F3FF for a Foundry/governance boundary, fillColor=#EFF6FF for a platform boundary, matching each group's strokeColor) behind a group of related nodes (added earlier in the XML so it renders behind, not as a true mxGraph parent/child container) to visually group them -- a filled tint reads as more finished than a transparent outline. Badge the group with a real icon representing what the group actually is, as a separate shape=image cell layered near the group's top-left corner, with the text label (a separate plain style="text;html=1;..." cell, not the group rectangle's own value) offset to the right of the badge rather than overlapping it -- confirmed on QLT-001 (2026-09-24) that a "Microsoft Foundry project" group with no Foundry badge and a "Local developer workstation" group with no device badge both read as incomplete once a reviewer compared them to the fully-iconed nodes inside. Give every icon in the diagram the same geometry (for example 64x64) -- badges included. A first pass at this used a smaller size (24-28px) for group badges than for the main nodes; the user immediately flagged it as inconsistent, and separately, some official icons (a thin ribbon mark like "AI Foundry") visually read as smaller than a bolder icon (a solid hexagon) even at the exact same bounding box, because the artwork itself uses less of its own canvas -- render a same-size comparison strip (see the size-check pattern below) before assuming equal geometry means equal visual weight. Center a group's main icon(s) within the group's width, not flush against its left edge next to the badge column. A first pass placed the badge and the main icons in the same left-aligned column, leaving a wide unused strip down the right side of every group -- confirmed on QLT-001 (2026-09-24) that this reads as unfinished ("icons hugging the wall instead of standing in the room"). Compute icon_x = group_x + (group_ width - icon_width) / 2 for the main icons; leave the header badge left-aligned next to its label, since a badge-plus-label header is conventionally left-aligned like a title bar and centering it would look stranger, not better. Use a small, fixed corner radius on group rectangles instead of rounded=1's default (which reads as an oversized pill on a large box): rounded=1;arcSize=5;absoluteArcSize=1; fixes the radius at 5px regardless of the rectangle's size, rather than scaling the radius as a percentage of the shorter side. Connect nodes with edges styled per relationship type, not one identical arrow for everything -- see "Differentiate edges by meaning" below. Keep node count small and labels short -- this is still a bite-sized diagram, not a full topology map.

Differentiate edges by meaning

A diagram where every edge is an identical black arrow forces the reader to infer what kind of relationship each one is. Give each distinct kind of relationship its own color, dash pattern, and short label, reusing this repository's palette so the meaning stays consistent across controls:

  • Solid black or gray, no label or a short factual label -- plain sequential/data flow (one node's output directly becomes the next node's input).
  • Teal (strokeColor=#00A3BF) labeled "notifies" -- a message sent to a human or a notification channel.
  • Purple (strokeColor=#A855F7 or #7E22CE) labeled "invokes" -- a call into a governed/hosted component.

Note: an earlier version of this guidance recommended a dashed amber edge labeled "authenticates via" for auth/identity steps. Per "Decide what belongs in the diagram" above, authentication is now a prose note above the image, not a node or edge -- if a control's diagram still has an "authenticates via" edge, that is a sign it should be simplified, not a pattern to copy into a new diagram.

Prefer solid over dashed once dashed no longer carries real meaning. Dashed strokes are useful for a genuine distinction (for example "Foundry's own internal mechanism" vs. "this control's own code calling out"), but two real problems show up otherwise: (1) a dash's phase can land exactly at a label's edge and peek a couple of pixels beyond it -- switching the edge to solid avoids this specific symptom, though see the more general labelBackgroundColor problem below, which affects solid edges too; (2) once a diagram is simplified down to a single causal chain (see above), every edge in it is the same kind of "this produces that" relationship, so a dashed/solid split stops encoding any real distinction and is just inconsistent for its own sake -- confirmed on QLT-001 (2026-09-24), where dashed styling left over from a more complex, multi-actor version of the diagram no longer matched anything once the diagram was cut down to four nodes.

labelBackgroundColor on an edge's own value, or on a standalone style="text;..." cell used as a label, does not reliably produce a padded background -- confirmed on QLT-001 across several attempts (2026-09-25). The symptom: a connecting line appears to touch or run directly through the label's text on both sides, as if the white background box were sized exactly to the glyphs with zero padding. This is not a dash-phase artifact (it persists on solid edges too) and is not fixed by any of the following, each tried and confirmed not to work: padding the label's own text value with leading/trailing spaces (draw.io's own model strips or ignores this for width purposes); giving a standalone label cell an explicit, generous width/height in its mxGeometry (a plain text; style shape auto-sizes to fit its rendered content in draw.io's graph model on load, silently overriding whatever geometry the source XML declares); adding whiteSpace=wrap to that same text cell (does not override the auto-sizing behavior either). The fix that actually worked: stop relying on any text shape's own background entirely. Pair every label with two separate cells at the identical position and size: a plain rectangle with a real fill and no text (style="rounded=0;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=none;") sized generously wider than the text it will cover, plus a style="text;..." cell on top with no labelBackgroundColor of its own. Rectangles reliably honor their declared mxGeometry (proven by every icon and group box in this same diagram), so this is what actually creates real, verifiable padding -- confirm it by rendering, then cropping and viewing the label region at full (pre-resize) resolution, not by eyeballing the downscaled embed image, since the gap this fix produces is only a few pixels wide.

Don't duplicate a fact the prose above the diagram already states. If a detail is already established in the sentence introducing the image (for example "scored by a batch evaluation run"), don't also cram it into an edge label -- confirmed on QLT-001 (2026-09-24): adding "(batch eval run)" to an edge label that already had a full-sentence-worth of text made the label wide enough to visually collide with the arrowhead at the far end of its own routing segment. Add the qualifier to the prose (or shorten the segment/widen the gap) rather than to an already-long label.

<mxCell id="e1" value="" edge="1" parent="1" source="runner" target="teams"
        style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;strokeWidth=2;strokeColor=#00A3BF;exitX=0;exitY=0.5;entryX=0;entryY=0.5;">
  <mxGeometry relative="1" as="geometry" />
</mxCell>
<!-- Label as two separate cells at the same position, not the edge's own
     value/labelBackgroundColor -- see above for why. -->
<mxCell id="e1-bg" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=none;" value="" vertex="1">
  <mxGeometry x="640" y="121" width="70" height="18" as="geometry" />
</mxCell>
<mxCell id="e1-label" parent="1" style="text;html=1;align=center;verticalAlign=middle;fontSize=11;fontColor=#00A3BF;" value="notifies" vertex="1">
  <mxGeometry x="640" y="121" width="70" height="18" as="geometry" />
</mxCell>

Route edges deliberately -- floating connections cross and collide

mxGraph's default "floating" connection (no exitX/exitY/entryX/entryY, no waypoints) picks whatever point on each shape's perimeter is closest to the other shape's center. This looks fine for one isolated edge and produces two real, confirmed failure modes once a diagram has several:

  1. Edges cross each other when two edges leave the same source toward targets on opposite sides, because each one's floating exit point can end up more central than expected. Fix: pin exitX/exitY and entryX/entryY explicitly (fractions 0-1 of the shape's own bounding box) on every edge, and add edgeStyle=orthogonalEdgeStyle;rounded=0; so the line bends at right angles instead of drawing a diagonal.
  2. An edge cuts straight through an unrelated icon or label when its shortest path happens to pass through a group's badge/label header on the way from an interior node to a target outside the group. Fix: give the edge explicit waypoints (<Array as="points"><mxPoint x=".." y=".."/>...</Array> inside the edge's <mxGeometry>) that route it outside the group's bounding box first, then up or across to the target, instead of straight through the group's interior. Confirmed on QLT-001 (2026-09-24): two edges from a node inside a group to two nodes above the group both originally cut straight through that group's badge icon; adding one waypoint just outside each side of the group's bounding box before turning toward the target fixed it.

Separately, an edge's own auto-placed label can land exactly on top of a nearby node's label if the edge's midpoint happens to coincide with where that node's label sits below it -- confirmed on QLT-001 (2026-09-24), where a vertical edge's default centered label overlapped the source node's own label directly above it, rendering as garbled overlapping text. Fix: give the edge no value and add a separate manually positioned style="text;..." cell for its label instead, positioned in whatever free space actually exists (increase the gap between the two connected nodes first if none does), rather than trusting the edge's automatic midpoint placement.

A chain of nodes at the same height needs its connecting edges routed above or below the icon row, never through the icons' own vertical center. entryY=0.5/exitY=0.5 connects at each icon's vertical midpoint, which is inside the icon artwork when both nodes sit at the same height -- confirmed on QLT-001 (2026-09-24): a simplified left-to-right chain of four same-height icons rendered its connecting lines and labels directly behind the icon glyphs, invisible against the artwork. Fix: route every edge in the chain along a shared horizontal "spine" a fixed distance above the icon row instead -- exitX=0.5;exitY=0 (icon's top-center) with a waypoint at the same x a fixed offset above the icons (for example 20px), across to the target's x at that same spine height, then down into entryX=0.5;entryY=0 (target's top-center). Because the segments between different node pairs in a simple left-to-right chain don't share an x range, every edge can use the same spine height without colliding with its neighbors -- there's no need to stagger heights unless two edges actually cross the same x range.

Verify icon sizing and edge layout before calling it done

Two verification passes catch what "does it render at all" does not:

  1. Size comparison. Render every candidate icon at the same fixed geometry (for example a row of shape=image cells all sized 64x64) in a disposable test diagram before wiring them into the real one, and look at whether they read as visually equal -- not just whether the bounding box matches. A thin ribbon-style logo can look smaller than a solid geometric icon at an identical box size.

  2. Full-diagram visual review, specifically checking for: any label touching or overlapping the icon above it, any two edges crossing each other, any edge passing through an icon or a label instead of empty space, and how much unused white space the group boxes contain relative to their actual content (a box sized for content that got trimmed later reads as an unfinished layout). Treat "the command exited 0 and produced a PNG" as necessary, not sufficient.

  3. Scope review: does any node exist only to describe today's deployment/execution convenience rather than to explain why the control works (see "Decide what belongs in the diagram" above)? Does the diagram redraw the same decision branches "Logical design" already shows instead of showing building blocks and data flow? Both were real, repeated findings on QLT-001, not hypothetical risks -- check for them explicitly rather than assuming a diagram that renders cleanly is also well-scoped. For the Azure-scope layout, also check: does every box nest under the scope it really lives in (subscription, resource group, resource)? Does the outside-scope band hold exactly the things cleanup does not delete? Does the legend list every edge colour and boundary style and nothing else? Is nothing drawn as planned or pending? Does every label backdrop match the fill of the panel under it?

  4. A group's own boundary stroke can bisect a node's label that sits just inside it. Confirmed on QLT-001 (2026-09-25): a group box sized to end right at its icon row's bottom, with the icon's text label positioned just below that (a common layout, since labels conventionally sit under their icon), placed the group's dashed bottom edge exactly through the vertical middle of that label's text, rendering as a strikethrough. This is a distinct failure mode from "label overlaps the icon above it" in item 2 above -- the label doesn't touch its own icon at all, it collides with the group container's edge instead, so a review pass that only checks label-vs-icon overlap misses it. A first attempted fix -- enlarging the group to enclose the label with a 10px+ margin below it -- did not reliably resolve this (confirmed on a second render pass, same control, same day: the boundary still read as touching/underlining the label even after adding margin). The fix: keep every contained node's label fully outside the group -- matching how every other (non-grouped) node's label already sits outside any box in the same diagram -- rather than trying to size the group to enclose the label with margin. Don't stop at "outside," though: a first pass at this shrank the group down to just 4px of clearance below the icon row, which fixed the text collision but then read as visually cramped -- box edge nearly touching the icons -- next to the generous, un-boxed white space around every other node in the same diagram (confirmed on a third render pass, same control, same day, after the user flagged the cramped result as still not right). The padding that actually read as correct: roughly 20px of clear space between the icon row's bottom and the group's bottom edge, achieved by moving every node's label (grouped and ungrouped alike) down together by the same offset to open up that room, keeping every label row aligned at the same height across the whole diagram. Verify at full render resolution (crop and inspect the group region directly, not just eyeballing the full downscaled image), not only at the final resized embed dimensions -- and judge padding by comparison against the un-grouped nodes' own white space in the same image, not in isolation.

  5. Multiple edges converging on the same target's entry side need real visual separation, not just distinct entryX values. Confirmed on QLT-001 (2026-09-25): two edges entering the same icon with entryX=0.4 and entryX=0.6 (a 0.2 spread, roughly 13px apart on a 64px-wide icon) still read as one merged arrowhead at a glance. Spread convergent entries much further apart -- entryX=0.2/entryX=0.8 (a 0.6 spread) reads as two clearly distinct arrows. The same applies in reverse to multiple edges leaving the same source: give each its own exitX spread this wide too, not just a technically-different value, so the lines visibly diverge right from their source instead of overlapping for their first stretch.

  6. Render it:

    .venv/bin/python scripts/render_drawio_diagram.py \
        --input controls/<category>/<ID>/docs/architecture.drawio \
        --output controls/<category>/<ID>/media/architecture.png
    

    The export format embeds the source XML in the PNG's own metadata (xmlpng), so the committed image is also directly re-openable and re-editable in the VS Code draw.io extension, not just a dead-end raster -- a nice side benefit over the Mermaid pipeline's plain PNG.

  7. Verify the output visually before committing: open the rendered image and confirm every icon shows a real logo/glyph, not a broken-image placeholder. A broken image most often means either the icon: path is wrong relative to the .drawio file's directory, or (if hand-editing the style outside this script's placeholder mechanism) a raw ; snuck into an embedded data: URI -- mxGraph's style parser does a naive style.split(';') (confirmed 2026-09-24 by reading mxgraph/src/view/mxStylesheet.js in the bundled extension), so any literal semicolon inside a value silently truncates it. This is exactly why the render script's icon: placeholder expands to a non-base64, fully percent-encoded data:image/svg+xml,... URI instead of the more common data:image/svg+xml;base64,... form: the base64 form's own ;base64, segment contains the one semicolon that breaks it.

  8. Embed the image in the README, following this repository's existing <img>-with-caption convention:

    <p align="center">
        <img src="media/architecture.png" alt="<describe what the diagram shows>" width="900">
    </p>
    

    Do not add a "Source: docs/architecture.drawio ... re-render it with scripts/render_drawio_diagram.py" caption sentence after the image -- confirmed on VAL-001 and QLT-001 (2026-09-25) that this is authoring information (how a maintainer regenerates the picture), not something the reader of the control needs, and it was removed from both. The .drawio source being committed next to the image (see the next step) is enough for a future editor to find it; a diffable git history and the file's own presence in docs/ already answer "where does this come from" without spending a reader-facing sentence on it.

    The declared width must equal the actual rendered image's pixel width (this repository's own tests enforce that) -- resize the PNG first if the raw render is wider than is comfortable to read, and update width to match the resized file, not the original.

  9. Keep the .drawio source committed next to the image so a future edit only needs to change the source and re-run step 4.

Mermaid fallback (when the draw.io extension is unavailable)

The same pipeline this skill previously used exclusively still works and is still the right choice for a machine without the draw.io extension installed:

  1. One-time setup: mkdir -p .tooling/mermaid && cd .tooling/mermaid && npm init -y && npm install @mermaid-js/mermaid-cli @iconify-json/logos && cd - (.tooling/ is gitignored; never add these packages to a control's own dependency files).
  2. Write docs/architecture.mmd using architecture-beta syntax (service name(logos:microsoft-teams)[Teams Workflows], group id(icon)[Label], edges as from:SIDE --> SIDE:to).
  3. Pick icons from, in order: a user-supplied official asset in media/icons/ turned into a local pack with scripts/build_icon_pack.py (referenced as --local-icon-pack fwf#media/icons/fwf-icons.json, served with a CORS header the script already adds -- a locally-built pack fetched without one silently fails and renders a "?"); logos:<name> from the installed @iconify-json/logos set; azure:<name> from the community pack fetched by URL via --iconPacksNamesAndUrls; no icon at all if nothing fits.
  4. Render: python3 scripts/render_architecture_diagram.py --input docs/architecture.mmd --output media/architecture.png [--local-icon-pack ... ] [--chrome "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"].
  5. Verify visually, embed in the README, and keep the .mmd committed -- same as steps 5-7 of the draw.io workflow above.

Verify relationships against the actual code, not memory or a prior summary

Before drawing an edge between two building blocks, confirm what actually calls what by reading the control's own entry point (demo.py or equivalent), not by reasoning from an earlier design description or a mental model carried over from a previous session. Confirmed the hard way on QLT-001 (2026-09-24): an earlier pass drew az / azd auth login as the node that invokes the hosted agent, and drew the agent's output as flowing into a passive downstream "Eval definition" scorer. Reading demo.py directly showed both were wrong -- authentication is a one-time prerequisite with no outgoing calls of its own, and demo.py itself is the caller that directly invokes the agent (azd ai agent invoke) and directly triggers and reads the eval run (azd ai agent eval run, then openai_client.evals.runs.output_items.list); the agent's involvement in scoring happens through Foundry's own eval-run mechanism, not through a call chain demo.py orchestrates end to end. A visually polished diagram that draws the wrong caller is worse than an ugly one that draws the right one -- treat "does this match what the code actually does" as a required check, equal in weight to the visual checks in the previous section.

Do not add step numbers, even if asked for "reading order"

The Demo infrastructure setup (simplified) diagram is a component overview, not an execution trace -- docs/control-readme-template.md says so explicitly ("This is a component overview, not a numbered execution trace"). If a reviewer asks for a way to tell reading order from the image, resist adding ①②③-style sequence numbers to nodes or edges; that reintroduces the exact call-order framing the template rules out, and this control's own several CLI subcommands (run, evaluate, notify) are invoked as separate, independently-runnable steps by an operator, not one atomic top-to-bottom sequence a numbered diagram would honestly represent. Address the concern with descriptive edge labels (what relationship this is) instead of sequence numbers (when it happens).

What this does not replace

  • "Logical design" diagrams stay plain flowchart code blocks -- decision flow, not building blocks, and no rendering pipeline is needed for them.
  • A control with no interesting real-world services to show (for example, a guided exercise with no deployed components) should keep stating "Not applicable" rather than forcing an icon diagram where none is warranted.

04 同仓库更多 Skills