| name | system-design-diagramming |
| description | Draw system diagrams in the Archify visual language: a typed JSON spec rendered as dark-canvas SVG with numbered lanes, semantic node colors, masked edge labels, and a legend. Covers architecture, workflow, sequence, dataflow, and lifecycle views. Use for any design-session diagram. |
| metadata | {"triggers":{"keywords":["archify","diagram","architecture diagram","sequence diagram","data flow diagram","lifecycle diagram","swimlane","draw the system"]}} |
System Diagramming (Archify Style)
Priority: P1 (HIGH)
Author a typed JSON spec, then render. Never hand-place pixels in prose, and never ship Mermaid as the deliverable.
Pick One Type
| Type | Use for |
|---|
architecture | Components, services, cloud and trust boundaries |
workflow | Processes, approval gates, runbooks, CI/CD |
sequence | Call chains, request lifecycles, async traces |
dataflow | Pipelines, ETL, lineage, consumers |
lifecycle | State transitions, retries, terminal states |
One type per diagram. A design doc usually needs architecture plus one of sequence or dataflow.
Render Path
- Check whether the Archify skill is installed (
archify/SKILL.md under any agent skills directory).
- Installed: author the JSON against its
schemas/<type>.schema.json, then run archify validate <type> <file>.json after every edit and archify deliver once at the end. A non-zero exit is never a success.
- Not installed: emit inline SVG directly, following the style contract. Same tokens, same geometry, same legend rules.
- Either way the spec is the source of truth: nodes carry
id, type, label, optional sublabel and tag; edges carry from, to, label, variant; groups list the ids they wrap.
Semantics Are Colors
- Node
type is meaning, not decoration: frontend, backend, database, cloud, security, messagebus, external.
- Edge
variant is meaning: default plain call, emphasis main request path, security auth or policy hop, dashed async or event.
- Never introduce a color outside that map, and never inline a literal hex that breaks dark/light parity.
- Group frames come in two kinds only:
region for deployment or ownership, security-group for a trust boundary.
Composition Rules
- One left-to-right main path; side branches leave the nearest main-path node.
- At most 12 primary nodes. Split the view before crowding it.
- Number every lane or stage as
01 / Label, in order.
- Every edge carries a label unless both endpoints already imply the protocol, direction, and sync behavior.
- Spacing means clear gap, not center distance: leave more than the label mask width plus 8px.
- Legend is mandatory and lists only the kinds actually present.
Repair Order
Fix in this sequence, one diagnosed control at a time: schema errors, then node overlap or out-of-range placement, then edges crossing an opaque node, then ambiguous corridors and crossings, then label clearance.
Anti-Patterns
- No Mermaid deliverable: read Mermaid for topology if given, then author fresh in this format.
- No edge through an unrelated node: always a hard failure, never an acceptable trade.
- No label deleted to fix geometry: labels are data; reroute instead.
- No decorative accent: every saturated color maps to a node or relationship meaning.
- No coordinates planned in prose: write the spec, render, then read the diagnostics.
References
