hersaintel/stack-diagram

Was macht stack-diagram?

Hermes-Integration

Löse <skill> zum Verzeichnis auf, das diese SKILL.md enthält, nicht zum Projekt-Arbeitsverzeichnis. Führe gebündelte Skripte mit terminal über Python mit zitierten absoluten Pfaden aus. Verwende read_file für Vorlagen/Referenzen und write_file/patch für Artefakte. Bevorzuge eine isolierte Python-Umgebung für Playwright; ein reiner Import beweist noch nicht, dass der Browser-Treiber funktioniert.

Bei repository-basierten Anfragen dokumentiere zuerst die Belege für Knoten und Kanten. Abhängigkeiten begründen keine Laufzeittopologie. Behalte geschlussfolgerte Beziehungen als Annahmen bei; frage nach, wenn Mehrdeutigkeit die Architektur verändern würde. Explizite, vom Benutzer bereitgestellte Topologie ist ein Beleg. Lese niemals Geheimnisse oder nicht zusammenhängende Dateien, um einen Stack zu entdecken.

Liefere lokale Dateien mit MEDIA:/absoluter/pfad/zu/out.html und MEDIA:/absoluter/pfad/zu/out.png (plus das dunkle PNG) aus; verwende vision_analyze, um beide gerenderten Designs zu überprüfen. HTML ist die alleinige visuelle Quelle der Wahrheit; PNGs stammen von Chromium, nicht von einem unabhängigen SVG/PIL-Renderer. Markiere eine Datei nicht als ausgeliefert, bevor sie existiert. Dieser Skill ruft weder Brag auf noch modifiziert er es. Verwende stack-video nur, wenn ein Video angefordert wird; es ist ein unabhängiges Geschwisterkind, kein erforderlicher Schritt.

Upstream-Skripte/Ressourcen bleiben von caru-ini/stack-diagram erhalten; siehe UPSTREAM.md dieses Pakets. Die optionalen Galerieanweisungen unten erfordern weiterhin ihre eigene ausdrückliche Zustimmung; die Installation oder Veröffentlichung dieses Pakets ist keine Galeriezustimmung.

Produziert Architekturdiagramme im Ingenieurszeichnungs-Stil: echte Logos auf weißen Kacheln, beschriftete Gruppenboxen (wie Cloud-Vendor-VPC-Diagramme), orthogonale Pfeile mit Monospace-Beschriftungen, auf einem kühlen Millimeterpapier-Hintergrund. Eine eigenständige HTML-Datei ist die Quelle der Wahrheit; PNG / TSX / Artefakt werden daraus abgeleitet.

Voraussetzungen

• Python 3.9+ (nur Standardbibliothek für fetch_icons.py, build.py und share.py)
• Netzwerkzugriff auf die Icon-Quellen (svgl.app, raw.githubusercontent.com, cdn.jsdelivr.net, aws.amazon.com und d1.awsstatic.com für AWS-Icons, services.google.com für Google Cloud-Icons, learn.microsoft.com und arch-center.azureedge.net für Azure-Icons, sowie die eigene Website oder das Repository der Marke für name=URL) beim Abrufen von Icons
• Playwright + Chromium für render_png.py: pip install playwright && python3 -m playwright install --with-deps chromium

Arbeitsablauf

1. Inhalt festlegen (Knoten, Gruppen, Kanten)
2. Icons abrufen – scripts/fetch_icons.py
3. Koordinaten planen – references/geometry.md lesen
4. HTML aus assets/template.html erstellen – scripts/build.py
5. Ein PNG rendern und ansehen vor der Auslieferung
6. In den angeforderten Formaten ausliefern
7. Optional zur öffentlichen Galerie teilen

Schritt 1 – Inhalt

Aus der Liste der Technologien/Dienste des Benutzers entscheiden:

• Knoten: jede Technologie = ein Knoten (Name + eine kurze, kleingeschriebene Rolle wie http server, sqlite db)
• Gruppen: einen Kasten um Dinge zeichnen, die eine Laufzeit, einen Anbieter oder ein Repository teilen (z. B. eine Cloud-Anbieter-Box, die eine Laufzeit-Box enthält; eine Monorepo-Box für Tooling). Eine Verschachtelungsebene ist in Ordnung; tiefer wird unübersichtlich. Gruppenbeschriftungen in der Schreibweise der Marke schreiben (GitHub, npm); die Vorlage zeigt sie wie geschrieben.
• Kanten, drei Arten:
  • akzentfarben durchgezogen = der primäre Anfrage-/Datenfluss (ein durchgehender Pfad liest sich am besten)
  • neutral durchgezogen = sekundäre interne Verbindungen
  • neutral gestrichelt = Entwicklung-/Bereitstellungsbeziehungen (CI, Git-Hooks, IaC-Deployment)

Wenn der Benutzer nur eine flache Liste von Werkzeugen angegeben hat, sinnvolle Gruppen und Flüsse aus den Werkzeugen selbst ableiten – nur nachfragen, wenn ein Werkzeug mehrdeutig genug ist, dass das Diagramm in beide Richtungen falsch wäre.

Schritt 2 – Icons

python3 scripts/fetch_icons.py <icons-verzeichnis> tanstack hono drizzle "betterauth:better-auth" "orpc=https://orpc.unnoq.com/logo.webp"
python3 scripts/fetch_icons.py <icons-verzeichnis> "aws:aws/AWS-Cloud-logo" "vpc:aws/vpc" "fargate:aws/fargate" "s3:aws/s3"
python3 scripts/fetch_icons.py <icons-verzeichnis> "gcp:google-cloud" "run:gcp/cloud-run" "lb:gcp/load-balancing" "sql:gcp/cloud-sql"
python3 scripts/fetch_icons.py <icons-verzeichnis> "azure:azure/Azure-A" "app:azure/app-service" "vnet:azure/vnet" "sql:azure/sql-database"

Spezifikationsformen: name (Name als Slug verwendet), name:slug (anderer Slug), name=URL (explizite URL), name:aws/<Name> (offizielles AWS-Icon), name:gcp/<Produkt> (offizielles Google Cloud-Icon), name:azure/<Name> (offizielles Azure-Icon). Das Skript versucht, in dieser Reihenfolge: svgl → devicon → gilbarbara/logos, schreibt Dateien plus manifest.json und kennzeichnet Icons, deren Füllung weiß ist. svgl (svgl.app) ist zuerst, weil es aktuelle offizielle Marken für moderne Entwickler-Brands (TanStack, Better Auth, Hono...) führt. Wenn ein Logo helle/dunkle Versionen hat, wird die helle zu <name> (Kacheln sind in beiden Designs weiß) und die dunkle als <name>_dark für Gruppenbeschriftungen gespeichert. svgl wird nur durch exakten Titel abgeglichen, ein Fehlschlag führt also einfach zum nächsten. Seine API stellt auch wordmark-Varianten bereit – gelegentlich nützlich für eine breite Gruppenbeschriftung, niemals für Kacheln.

Regeln, die mehr zählen als die Mechanik:

• Ein Logo niemals umfärben. Das fällt Benutzern auf. Wenn ein Logo weiß oder zu hell für eine weiße Kachel ist, stattdessen auf eine dunkle Kachel (tile dark-Klasse) setzen, anstatt die Füllung zu ändern. Das white_fill-Flag im Manifest ist eine Heuristik – eine weiße Füllung kann ein inneres Detail auf einem farbigen Mark sein (tRPC, Ubuntu), also vor der Verwendung der dunklen Kachel einen Blick auf das SVG werfen.
• Nur offizielle Marken. simple-icons ist bewusst keine Quelle: seine Glyphen sind monochrome Neuzeichnungen, und Benutzer erkennen sie sofort als falsch. Wenn alle Quellen fehlschlagen (FAIL), die offizielle Datei finden und als name=URL übergeben – im Repository des Projekts suchen (Root logo*.svg, docs/, assets/, public/) und auf seiner Website (/logo.svg, /favicon.svg, /images/logo.svg). Manche Marken leben nur im Repository (Lefthook's ist logo_sign.svg im Root von evilmartians/lefthook).
• Abstrakte Konzepte erhalten Piktogramme, keinen Text. Ein Knoten wie "dev environment", "cron", "queue", "cache" oder "webhook receiver" hat keine Marke – stattdessen ein Lucide-Linienicon verwenden über name:lucide/<icon> (z. B. devenv:lucide/terminal, cron:lucide/clock; durchsuche lucide.dev/icons). Kein Text-in-einer-Kachel, kein Emoji.
• Subprodukte von Anbietern (Cloudflare D1/R2/KV...) haben normalerweise kein eigenes Logo: einfach das Logo des Anbieters auf der Kachel wiederverwenden und die Unterscheidung durch den Knotennamen tragen lassen ("Cloudflare D1" / "sqlite db").
• AWS verwendet AWS-eigene Icons. Jeder Dienst hat eines: mit name:aws/<Name> abrufen, aus dem offiziellen AWS-Iconpaket zur Laufzeit lesen (z. B. lambda:aws/lambda, aws:aws/AWS-Cloud-logo, s3:aws/s3). Das AWS- / Amazon--Präfix ist optional, gebräuchliche Akronyme funktionieren (s3, sqs, sns, ses, ecs, eks, ecr, elb, alb, nlb, iam, kms, msk, vpc), und ein Fehlschlag gibt jeden Namen aus. Die Slugs aws, amazonwebservices und aws-* führen zum selben Paket, und was es nicht enthält, erhält FAIL anstatt auf eine Drittanbieter-Kopie zurückzugreifen. Für einen Dienst immer das aws/-Präfix schreiben: Ein bloßes dynamodb durchläuft trotzdem die Drittanbieterkette. Das Paket und lose Icon-Dateien außerhalb von Repos halten: AWS erlaubt die Icons in Diagrammen, und eine Weiterverteilung ist nicht bestätigt.
• Das AWS-Bereich folgt AWS-eigenen Zeichnungsregeln. Dienstsymbole tragen ihr eigenes Quadrat und funktionieren auf hellem und dunklem Grund, also tile bare verwenden: Eine weiße Kachel verdoppelt nur den Rahmen. Personen und generische Knoten darin verwenden AWS-Allgemeinsymbole (user:aws/General-User; auch General-Users, General-Client, General-Internet, General-Server) in tile bare res mit dem lt/dk-Paar der Vorlage. Gruppen verwenden die group aws der Vorlage für AWS Cloud (mit aws:aws/AWS-Cloud-logo in der Beschriftung), plus region, az, vpc, private oder public für den Rest: eckige Ecken, nur Umriss, Beschriftung in Tinte, kein Anbieterton und ein 30px Icon bündig in der Ecke anstelle des 14px. Innerhalb einer VPC öffentliche und private Subnetze zeigen, wenn die Aufteilung bekannt oder sicher ableitbar ist (ein internetfähiger Load Balancer im öffentlichen; App-Server und Datenbanken im privaten): Eine flache VPC ist das Erste, was AWS-Leuten auffällt. Kanten darin verwenden eine Farbe und eine offene Pfeilspitze: <path class="aws" ... marker-end="url(#open)"/>, aws dash für Entwicklung/Deployment, einfache .el-Beschriftungen und keine Legende dafür. Knoten Amazon S3 / AWS Fargate nennen, nicht ein bloßes S3 / Fargate; eine Kurzform wie ALB kommt in die Rollenzeile unter den vollständigen Namen (Elastic Load Balancing). Namen können zwei Zeilen belegen, aber Amazon / AWS muss in der Zeile des ersten Wortes bleiben: Wenn es direkt nach dem Präfix umbrechen würde, diesen Knoten verbreitern (left:<centerX-76>px; width:152px).
• Google Cloud verwendet Google-eigene Icons. Mit name:gcp/<Produkt> abrufen, aus den offiziellen Google-Paketen zur Laufzeit lesen (z. B. run:gcp/cloud-run, lb:gcp/load-balancing, memorystore:gcp/memorystore). Nur Kernprodukte haben ein eigenes Icon (Cloud Run, Cloud SQL, Cloud Storage, BigQuery, GKE, Compute Engine, Vertex AI...). Jedes andere Produkt verwendet das Icon seiner Kategorie, wie Google-Richtlinie vorschreibt: Cloud Load Balancing und Cloud CDN erhalten beide Networking, Memorystore und Firestore erhalten beide Databases. Den Produktnamen schreiben, und das Skript wählt das Icon aus. Das Cloud / Google-Präfix ist optional, einige Kurzformen funktionieren (vpc, iam, kms, iap, gce, gcs), und ein Fehlschlag gibt jeden Namen aus. gcp/storage ist die Kategorie Storage; Cloud Storage ist gcp/cloud-storage. Die Slugs gcp-* und google-cloud-* führen zu denselben Paketen, und was sie nicht enthalten, erhält FAIL anstatt auf eine Drittanbieter-Kopie zurückzugreifen: Diese Kopien sind die ausgemusterten hexagonförmigen Icons, die Google nicht mehr verwendet haben möchte. Für ein Produkt immer das gcp/-Präfix schreiben: Ein bloßes bigquery durchläuft trotzdem die Drittanbieterkette. gcp:google-cloud ist das Google Cloud-Mark für die Gruppenbeschriftung. Gemini und Firebase sind nicht in den Paketen: das bloße gemini und firebase verwenden. Die Pakete und losen Icon-Dateien außerhalb von Repos halten: Google bietet die Icons für Diagramme und Dokumentation an, und eine Weiterverteilung ist nicht bestätigt.
• Google Cloud-Diagramme behalten den normalen Stil mit Googles Gruppen bei. Googles eigene Diagramme (durchgehendes blaues Panel, horizontale Karten) werden bewusst nicht kopiert: Icons kommen auf die normale weiße Kachel, und Kanten sowie Legende bleiben wie üblich. Gruppen verwenden die group gcp der Vorlage für Google Cloud (mit gcp:google-cloud in der Beschriftung), plus vpc, region, subnet oder zone. Ein VPC ist global und ein Subnetz ist regional, also die Region innerhalb des VPC platzieren, niemals den VPC innerhalb einer Region. Globale und serverlose Dienste (ein externer Load Balancer, Cloud Storage, Cloud Run) bleiben außerhalb des VPC. Da Icons geteilt werden, immer den vollständigen Namen des Produkts schreiben (Cloud Load Balancing, nicht LB), und einen Knoten verbreitern, dessen Name umbrechen würde (left:<centerX-76>px; width:152px).
• Azure verwendet Microsoft-eigene Icons. Jeder Dienst hat eines: mit name:azure/<Name> abrufen, aus dem offiziellen Microsoft-Paket zur Laufzeit lesen (z. B. app:azure/app-service, azure:azure/Azure-A, vault:azure/key-vault). Das Azure- / Microsoft--Präfix und ein Plural-s sind optional, gebräuchliche Kurzformen funktionieren (aks, vm, vnet, nsg, waf, blob, cosmos, redis, postgres, functions, front-door, apim, ai-search), und ein Fehlschlag gibt jeden Namen aus. Die Slugs azure, microsoft-azure und azure-* führen zum selben Paket, und was es nicht enthält, erhält FAIL anstatt auf eine Drittanbieter-Kopie zurückzugreifen. Für einen Dienst immer das azure/-Präfix schreiben: Ein bloßes cosmos durchläuft trotzdem die Drittanbieterkette. Microsoft Entra ID hat ein separates Icon-Set: seine offizielle Datei als name=URL übergeben. Microsoft erlaubt diese Icons nur in Architekturdiagrammen, Schulungsmaterialien und Dokumentation. Niemals eines zuschneiden, spiegeln, drehen oder verformen, nur für den Microsoft-Dienst verwenden, den es repräsentiert, und das Paket sowie lose Icon-Dateien außerhalb von Repos halten.
• Azure-Diagramme behalten den normalen Stil mit Microsofts Gruppenfarben bei. Microsofts eigene Diagramme werden bewusst nicht kopiert: Icons kommen auf die normale weiße Kachel, und Kanten sowie Legende bleiben wie üblich. Gruppen verwenden die group azure der Vorlage für Azure (mit azure:azure/Azure-A in der Beschriftung), plus rg, region, vnet, subnet oder zone, und eine vnet- oder subnet-Beschriftung trägt ihr Icon (vnet:azure/vnet, subnet:azure/subnet). Ein VNet gehört zu einer Region, also wird es innerhalb der Region platziert. Globale Dienste wie Front Door bleiben außerhalb der Region. App Service sitzt außerhalb des VNet, es sei denn, es läuft in einer App Service-Umgebung, und ein über einen privaten Endpunkt erreichter PaaS-Dienst kann mit private endpoint als Rolle darin sitzen. Microsoft verlangt den vollständigen Dienstnamen neben jedem Icon (Azure SQL Database, nicht SQL), also einen Knoten verbreitern, dessen Name umbrechen würde (left:<centerX-76>px; width:152px).
• Die Regeln eines Anbieters gelten nur für seinen eigenen Bereich. Die AWS-, Google Cloud- und Azure-Regeln gelten nur innerhalb der Gruppe dieses Anbieters, selbst wenn das Diagramm nichts anderes zeigt. Alles außerhalb davon, wie ein Benutzer daneben oder eine Kante, die hineinführt, behält die normalen Kacheln, Gruppen, Kanten und Legende.
• Nicht-Marken-Knoten (Benutzer, Browser, Internet, Geräte, Bare-Metal-Server): Eine Glyphe aus assets/generic/ in das Icons-Verzeichnis unter dem Knotennamen kopieren oder name:lucide/<icon> verwenden – kein Emoji. Dies sind keine Markenlogos, daher ist es in Ordnung, sie in der Tintenfarbe des Diagramms einzufärben (das Abrufskript macht das für Lucide automatisch).
• Gruppenbeschriftungs-Icons werden mit 14px gerendert – sie benötigen ein quadratisches Glyphen-Mark. Wortmarken und breite Wort-Bild-Marken verschwimmen bei dieser Größe; wenn das Haupticon eine Wortmarke ist, das quadratische Icon der Marke separat für die Beschriftung abrufen (svgl hat es normalerweise; ansonsten das eigene Icon oder Favicon des Projekts).
• Gruppenbeschriftungen sitzen auf dem Farbton der Gruppe, nicht auf einer weißen Kachel, daher verschwindet im dunklen Design ein Mark mit schwarzen Teilen dort. Wenn fetch_icons.py <name>_dark gespeichert hat, das lt/dk-Paar der Vorlage in der Beschriftung verwenden; wenn es keine dunkle Variante gibt und das Mark schwarze Teile hat, dem <img> in der Beschriftung die Klasse plate hinzufügen (weißer Hintergrund, nur dunkles Design).
• Raster-Logos (png/webp) sind in Ordnung; das build-Skript wandelt sie in data-URLs um.

Schritt 3 – Koordinaten

references/geometry.md lesen für das vollständige Layout-System. Basis: body ist 1600 × 900, und die gesamte Zeichnung verwendet Pixel-Koordinaten mit absolute-Positionierung. Ein Raster von 8px ist die Granularität für Ausrichtung.

Schritt 4 – HTML erstellen

python3 scripts/build.py <icons-verzeichnis> <svg-dir>

Erzeugt eine einzelne SVG-Datei in <svg-dir>/<slug>.svg (wobei <slug> aus dem Arbeitsverzeichnisnamen stammt). Das SVG enthält beide Designs (hell/dunkel) und die Legende eingebettet.

Schritt 5 – Rendern und Qualität prüfen

python3 scripts/render_png.py <svg-path> --light --png <output-pfad>/light.png --width 1600
python3 scripts/render_png.py <svg-path> --dark --png <output-pfad>/dark.png --width 1600

Die gerenderten PNGs mit vision_analyze überprüfen. Gibt es überlappende Beschriftungen? Ist der primäre Fluss erkennbar? Sind die Icons erkennbar und korrekt? Diese Prüfung mit dem Benutzer teilen, wenn er/sie sie sehen möchte.

Schritt 6 – Ausliefern

python3 scripts/to_html.py <svg-path> --output <output-pfad>/stack.html

Oder falls gewünscht:

python3 scripts/to_tsx.py <svg-path> --output <output-pfad>/stack.tsx
python3 scripts/patch_artifact.py --svg <svg-path> --output <output-pfad>/artifact.md

Erwartete Ausgabe:

MEDIA:/path/to/stack.html
MEDIA:/path/to/light.png
MEDIA:/path/to/dark.png

Schritt 7 – Optionale Veröffentlichung

Nur auf ausdrückliche Aufforderung: Erfordert eine GITHUB_TOKEN-Umgebungsvariable. Ein Repository-Ziel und einen Pfad angeben; das Skript share.py kümmert sich um das Commit-Erstellen in einem vorkonfigurierten Gallery-Repository.

Beispiel

Ein Benutzer fragt: "Erstelle ein Diagramm für einen Full-Stack-Anwendung: React + Vite-Frontend, Hono-API, Drizzle-ORM, Turso-Datenbank, Bereitstellung auf Cloudflare Workers"

Inhalt:

• Knoten: React (UI-Bibliothek), Vite (Build-Tool), Hono (API-Framework), Drizzle (ORM), Turso (SQLite-DB), Cloudflare Workers (Runtime)
• Gruppen: Frontend (React, Vite), API (Hono, Drizzle), Datenbank (Turso), Cloudflare (Workers)
• Kanten: Akzentfarben durchgezogen von Vite → React → Hono → Drizzle → Turso, durchgezogen von Cloudflare Workers → Hono (sekundär)

Icons abrufen:

python3 scripts/fetch_icons.py <icons> react vite hono drizzle turso cloudflare

Vorlage

Siehe assets/template.html.

Das Obige ist der vollständige Inhalt von SKILL.md.