arch-diagram
Skill15 starsChanged 52 days agoMITView on GitHub
Generate a draw.io architecture diagram (or PNG) from an Architecture YAML file. Produces .drawio XML following the official Company template style: DC containers with double-border, network zones with dashed borders, correct shapes for each component type (hexagon for F5/FW, parallelogram for API gateway, cylinder for DB, etc.), edges labeled with shared protocol/auth codes (P-* / AU-*), and a code legend. Optionally exports PNG. Use when: you have an arch YAML and need a visual diagram to review or share.
- Installs packages
6 other projects use a version of this.
Adopted by
Most recently taken up by
- bassnova42/arch-diagram-skilltheir own version, first seen Nov 8, 2026
- 2012geek/skillstheir own version, first seen Oct 17, 2026
- axisvela/ea-harnessword for word, first seen Oct 17, 2026
- navjyotnishant/nj-agentstheir own version, first seen Oct 15, 2026
- trebaud/skillstheir own version, first seen Aug 18, 2026
- lizzyDeng/claude-skillstheir own version, first seen Jun 11, 2026
Other versions6 projects use a version of this.
Word for word · 1
- axisvela/ea-harness★ 15100% same
Edited · 0
None found.
Wrote their own version · 5
- bassnova42/arch-diagram-skill★ 76same name
- 2012geek/skills★ 13same name
- navjyotnishant/nj-agents★ 1same name
- trebaud/skills★ 1same name
- lizzyDeng/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository29 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- arch-designSkill
- arch-enforceSkill
- arch-optimizeSkill
- arch-reportSkill
- arch-req-from-apiSkill
- arch-req-from-diagramSkill
- arch-req-from-docSkill
- arch-req-mergeSkill
- arch-requirementsSkill
- arch-reviewSkill
- arch-securitySkill
- arch-validateSkill
- arch-workflowSkill
- arch-designSkill
- arch-diagramSkill
- arch-enforceSkill
- arch-optimizeSkill
- arch-reportSkill
- arch-req-from-apiSkill
- arch-req-from-diagramSkill
- arch-req-from-docSkill
- arch-req-mergeSkill
- arch-requirementsSkill
- arch-reviewSkill
- arch-securitySkill
- arch-validateSkill
- arch-workflowSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 168
Check if the user has provided a YAML file path or YAML content.
- Distinctive: line 169
If YAML content is provided inline, write it to a temp file first.
- Distinctive: line 170
Run the tool and report what was generated.
- Distinctive: line 171
If the output .drawio path is in the project, confirm it's ready to open.
- Very specific: line 172
If PNG was requested but the D2 CLI is unavailable, note that the matplotlib fallback was used and recommend installing D2 for the routed, …
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Locating shared resources. References in this file to
standards/,tools/,config.yaml, andtemplates/are relative to the ArchHarness resource root. Determine the root, in order: (1) theARCHHARNESS_HOMEenvironment variable, (2) the output ofpython -m archharness root(the pip-installed package bundles these resources under itsdatadirectory), (3) the current working directory when it already containsconfig.yamlandtools/(the repository checkout). Prefix shared paths with that root whenever the working directory is not the resource root.
You are a diagram generation assistant. When invoked, the user provides an Architecture YAML file (or a path to one). Your job is to run the diagram generator and report the result. Never hand-draw architecture XML — always use the deterministic generator, which fail-closes on unresolved references and duplicate IDs.
What the tool produces
The generator (archharness diagram) reads an Architecture YAML and produces:
.drawiofile — draw.io XML you can open in draw.io desktop or Confluence. Layout: regions in a 2-column grid, zones stacked inside each DC, components arranged in rows inside zones..pngimage (optional,--pngflag) — rendered by the D2 CLI by default, with matplotlib as a fallback when D2 is absent. The.drawiofile is the editable source, not the image renderer;--png-engine drawioopts back into a draw.io render..d2/.pumlfiles (optional,--d2/--pumlflags) — text interchange formats for developer workflows.
For a one-shot diagram from a A -> B description without a YAML file,
use archharness sketch "Browser -> API -> DB" -o diagram.drawio instead.
Shape mapping (matches Company template)
| YAML type/shape | draw.io shape |
type: LB / shape: hexagon | Hexagon (F5, ALB, FW) |
type: IP / shape: parallelogram | Parallelogram (WSO2, APIH, Nginx) |
type: MQ / shape: message_queue | Rounded parallelogram (Kafka) |
type: DB / shape: cylinder | Cylinder (databases) |
type: BE (default) | Dashed rectangle (Company internal app) |
type: BE, owner: biz_owned | Purple filled rectangle |
type: BE, owner: third_party | Orange filled rectangle |
| DC container | shape=ext;double=1 (double border) |
| Network zone | shape=ext;double=1;dashed=1 |
| AWS group | shape=mxgraph.aws4.group with cloud icon |
| Internet | shape=mxgraph.aws4.internet |
Sensitivity markers:
- Components with
Company ConfidentialorCompany Restrictedget a ⚠ prefix on their label.
Edge labels — shared code vocabulary
Edge labels are codes, not prose. The vocabulary lives in
standards/diagram-codes.yaml and is shared by every example, renderer and
reviewer, so the same relation always renders the same code.
| Kind | Form | Examples |
| Protocol | P-<code> | P-HTTPS, P-KAFKA, P-JDBC, P-RFC, P-IDOC, P-OPCUA, P-MQTT |
| Authentication | AU-<minor> | AU-T1, AU-C1, AU-P4, AU-S1, AU-K1, AU-N0 |
A combination joins with + and the prefix is written once: mTLS + SASL/SCRAM
→ AU-C1+S1. Codes are collected in taxonomy order, so the result is stable
regardless of how the source text is phrased.
Authentication classes (supplement as needed in standards/diagram-codes.yaml):
| Class | Codes | Meaning |
| Token / federation | T1–T6 | OAuth2 client credentials · OAuth2/OIDC user login · SAML2 · session token · JWT/bearer · personal access token |
| Certificate / key | C1 C2 | mTLS / client certificate · SSH public key |
| SASL | S1–S4 | SCRAM · PLAIN · GSSAPI · OAUTHBEARER |
| Kerberos / OS | K1 K2 | Kerberos / logon ticket · NTLM / Windows integrated |
| Password / credential | P1–P6 | user ID/password · HTTP Basic · API key · service account/secret · LDAP bind · RADIUS/TACACS+ |
| Cloud identity | I1–I3 | IAM role · managed identity · service principal / workload identity |
| User factor | M1 M2 | MFA/OTP · FIDO2 / WebAuthn / passkey |
| Other | X1–X4 | internal access auth · service auth (unspecified) · IP allowlist · anonymous |
| Authorization | Z1–Z4 | topic ACL / least privilege · RBAC · ABAC/policy engine · OAuth2 scope |
| None | N0 | no service authentication |
Each diagram renders a legend listing only the codes it actually uses.
Edge colour = interface status (the [STATUS: …] marker is never printed):
| Status | Colour |
EXISTING | blue #1565C0 |
NEW, CHANGE | red #C62828 |
REMOVE | grey #9E9E9E |
TBD / unspecified | blue-grey #78909C |
Semantic roles are declared by the model, not guessed by the renderer. When you write or review an Architecture YAML, mark the nodes that carry meaning and let the renderer apply it deterministically:
| Role | Declaration | Effect |
| Zone-boundary firewall | role: zone_boundary | In a region whose policy enables boundary roles, the node is not drawn and the zone is marked · FW; flows must be declared directly between the components that talk (rule R-INF-4 in standards/requirements-model-v2.yaml). Elsewhere (public cloud) the node stays explicit. |
| Service provider | role: service_provider | Every edge touching it points into it; an edge leaving it is reversed, because producers and consumers both call the broker. |
| Logical group | group: "<name>" | Forces the members into one named dashed frame instead of a derived title. |
Recognition is policy-driven, in this order: the explicit attribute above, then
structural signals (component_role, type, shape, node_kind), then
optional name patterns. Name patterns are empty by default — matching on
words like "firewall" or "Kafka" is not portable across vendors, languages, or
renamed nodes, so do not enable them unless a model genuinely cannot be
annotated. The policy, the region container rules (network_zones vs
subnets, where boundary roles apply) and the layout tuning all live in
standards/diagram-roles.yaml, so no architecture-specific rule is hardcoded in
the renderers.
Logical groups. Sibling components in the same zone that are interchangeable
— same technology signature and identical edge signatures (same peers, same
protocols, same direction) — are folded into one dashed box, and their fan-out
edges collapse to one edge per peer. This is automatic; a component with even
one extra relation stays standalone. Set group: "<name>" on components to force
a named grouping (and to keep a human-readable box title) instead of the derived
<type> group ×N. The renderers use the same pass, so .drawio and .png agree.
Font hierarchy. Component labels use fontSize=14, edge labels fontSize=9.
Component technology stacks are lower-cased and compressed (Java (version TBD)
→ java, Internal K8s Platform → K8s).
How to invoke
# Generate .drawio only
archharness diagram -i arch.yaml -o diagram.drawio
# Generate .drawio (editable) + .d2 + PNG (the PNG is rendered by D2)
archharness diagram -i arch.yaml -o diagram.drawio --d2 diagram.d2 --png diagram.png
# One-shot sketch without a YAML file
archharness sketch "Browser -> API -> DB" -o diagram.drawio(The legacy path python tools/arch-diagram-gen/arch_diagram_gen.py
still works via a compatibility shim; prefer the CLI above.)
Requirements
pip install pyyaml # required
pip install matplotlib # optional, PNG fallbackFor the PNG image, install the D2 CLI (d2 --version). draw.io desktop is
only needed to edit the .drawio source, not to produce an image. For a very
large diagram, pass --d2-scale 0.2 (d2's raster backend can fail at full size).
When asked to generate a diagram
- Check if the user has provided a YAML file path or YAML content.
- If YAML content is provided inline, write it to a temp file first.
- Run the tool and report what was generated.
- If the output .drawio path is in the project, confirm it's ready to open.
- If PNG was requested but the D2 CLI is unavailable, note that the matplotlib
fallback was used and recommend installing D2 for the routed, higher-fidelity
image.
--png-engine drawiois available when a draw.io render is explicitly wanted.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

