stack-diagram

Was macht stack-diagram?

Erzeugt Architekturdiagramme im Ingenieursstil: echte Logos auf weißen Kacheln, beschriftete Gruppenboxen (wie Cloud-Vendor-VPC-Diagramme), orthogonale Pfeile mit Monospace-Beschriftungen auf einem coolen Graphpapier-Hintergrund. Eine eigenständige HTML-Datei ist die Quelle der Wahrheit; PNG / TSX / Artifact 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 Site oder Repo der Marke für name=URL) beim Abrufen der Icons
• Playwright + Chromium für render_png.py: pip install playwright && python3 -m playwright install --with-deps chromium

Workflow

1. Inhalt festlegen (Knoten, Gruppen, Kanten)
2. Icons abrufen – scripts/fetch_icons.py
3. Koordinaten planen – referenzen/geometrie.md lesen
4. HTML aus assets/template.html bauen – scripts/build.py
5. Ein PNG rendern und anschauen, bevor es ausgeliefert wird
6. Im angeforderten Format ausliefern
7. Optional im öffentlichen Galerie teilen

Schritt 1 – Inhalt

Aus der Liste der Technologien/Dienste des Benutzers entscheiden:

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

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

Schritt 2 – Icons

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

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), name:k8s/<Ressource> (offizielles Kubernetes-Icon). Das Skript versucht in der Reihenfolge: svgl → devicon → gilbarbara/logos, schreibt Dateien plus manifest.json und markiert Icons, deren Füllfarbe weiß ist. svgl (svgl.app) steht an erster Stelle, da es aktuelle offizielle Marken für moderne Entwicklungsmarken (TanStack, Better Auth, Hono...) enthält. Wenn ein Logo helle/dunkle Versionen hat, wird die helle zu <name> (Kacheln sind in beiden Themes weiß) und die dunkle als <name>_dark für Gruppenbeschriftungen gespeichert. svgl wird nur nach exaktem Titel abgeglichen, ein Fehltreffer fällt einfach durch. Seine API stellt auch wordmark-Varianten bereit – gelegentlich nützlich für eine breite Gruppenbeschriftung, nie für Kacheln.

Regeln, die wichtiger sind als die Mechanik:

• Ein Logo niemals neu einfärben. Benutzer bemerken das. Wenn ein Logo weiß oder zu hell für eine weiße Kachel ist, auf eine dunkle Kachel setzen (tile dark-Klasse), 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 einen Blick auf das SVG werfen, bevor zur dunklen Kachel gegriffen wird.
• Nur offizielle Marken. simple-icons ist bewusst keine Quelle: seine Glyphen sind monochrome Neuzuzeichnungen, und Benutzer erkennen sie auf den ersten Blick als falsch. Wenn alle Quellen fehlschlagen (FAIL), die offizielle Datei suchen und als name=URL übergeben – im Repo des Projekts (Wurzel logo*.svg, docs/, assets/, public/) und auf seiner Website (/logo.svg, /favicon.svg, /images/logo.svg). Manche Marken leben nur im Repo (Lefthooks ist logo_sign.svg im Wurzelverzeichnis von evilmartians/lefthook).
• Abstrakte Konzepte bekommen Piktogramme, keinen Text. Ein Knoten wie „Entwicklungsumgebung", „Cron", „Warteschlange", „Cache" oder „Webhook-Empfänger" hat keine Marke – ein Lucide-Linien-Icon über name:lucide/<icon> verwenden (z.B. devenv:lucide/terminal, cron:lucide/clock; lucide.dev/icons durchsuchen). Kein Text in einer Kachel, kein Emoji.
• Vendor-Subprodukte (Cloudflare D1/R2/KV...) haben in der Regel kein eigenes Logo: einfach das Anbieter-Logo auf der Kachel wiederverwenden und die Unterscheidung durch den Knotennamen tragen („Cloudflare D1" / „sqlite db").
• AWS verwendet AWS-eigene Icons. Jeder Dienst hat eines: mit name:aws/<Name> abrufen, zur Laufzeit aus dem offiziellen AWS-Icon-Paket lesen (z.B. lambda:aws/lambda, aws:aws/AWS-Cloud-logo, s3:aws/s3). Das Präfix AWS- / Amazon- ist optional, gängige Akronyme funktionieren (s3, sqs, sns, ses, ecs, eks, ecr, elb, alb, nlb, iam, kms, msk, vpc), und ein Fehltreffer gibt jeden Namen aus. Die Slugs aws, amazonwebservices und aws-* gehen zum selben Paket, und was es nicht enthält, scheitert mit FAIL anstatt auf eine Drittanbieter-Kopie zurückzufallen. Immer das aws/-Präfix für einen Dienst schreiben: ein reines dynamodb durchläuft trotzdem die Drittanbieter-Kette. Das Paket und lose Icon-Dateien außerhalb von Repos halten: AWS erlaubt die Icons in Diagrammen, und eine Weiterverteilung ist unbestätigt.
• Der AWS-Bereich folgt AWS-eigenen Zeichenregeln. Dienst-Icons tragen ihr eigenes Quadrat und funktionieren auf hellen und dunklen Hintergründen, also tile bare verwenden: eine weiße Kachel verdoppelt nur den Rahmen. Personen und generische Knoten darin nutzen AWS allgemeine Icons (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 Anbieter-Farbton und ein 30px-Icon bündig in der Ecke anstatt des 14px-Icons. Innerhalb einer VPC öffentliche und private Subnetze zeigen, wenn die Aufteilung bekannt ist oder sicher abgeleitet werden kann (ein internetfähiger Load Balancer in öffentlichen; App-Server und Datenbanken in privaten): eine flache VPC ist das Erste, was AWS-Leute bemerken. Kanten darin verwenden eine Farbe und eine offene Pfeilspitze: <path class="aws" ... marker-end="url(#open)"/>, aws dash für Dev/Deploy, einfache .el-Beschriftungen und keine Legende dafür. Knoten Amazon S3 / AWS Fargate nennen, nicht ein reines S3 / Fargate; eine Kurzform wie ALB kommt in die Rollenzeile unter den vollständigen Namen (Elastic Load Balancing). Namen können zwei Zeilen einnehmen, aber Amazon / AWS müssen in der Zeile des ersten Wortes bleiben: wenn der Name 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 Googles Leitfaden vorschreibt: Cloud Load Balancing und Cloud CDN bekommen beide Networking; Memorystore und Firestore beide Datenbanken. Den Produktnamen schreiben und das Skript wählt das Icon aus. Das Präfix Cloud / Google ist optional, einige Kurzformen funktionieren (vpc, iam, kms, iap, gce, gcs), und ein Fehltreffer gibt jeden Namen aus. gcp/storage ist die Storage-Kategorie; Cloud Storage ist gcp/cloud-storage. Die Slugs gcp-* und google-cloud-* gehen zu denselben Paketen, und was sie nicht enthalten, scheitert mit FAIL anstatt auf eine Drittanbieter-Kopie zurückzufallen: diese Kopien sind die ausgemusterten Hexagon-Icons, die Google nicht mehr verwendet haben möchte. Immer das gcp/-Präfix für ein Produkt schreiben: ein reines bigquery durchläuft trotzdem die Drittanbieter-Kette. gcp:google-cloud ist das Google Cloud-Zeichen für die Gruppenbeschriftung. Gemini und Firebase sind nicht in den Paketen: die reinen gemini und firebase verwenden. Die Pakete und lose Icon-Dateien außerhalb von Repos halten: Google stellt die Icons für Diagramme und Dokumentation zur Verfügung, und eine Weiterverteilung ist unbestätigt.
• Google Cloud-Diagramme behalten den normalen Stil mit Google-Gruppen. Googles eigene Diagramme (durchgehend blaues Panel, horizontale Karten) werden bewusst nicht kopiert: Icons kommen auf die normale weiße Kachel, und Kanten und 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 regional, also die Region innerhalb des VPC platzieren, niemals das 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 Produktnamen 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 Präfix Azure- / Microsoft- und ein Plural-s sind optional, gängige Kurzformen funktionieren (aks, vm, vnet, nsg, waf, blob, cosmos, redis, postgres, functions, front-door, apim, ai-search), und ein Fehltreffer gibt jeden Namen aus. Die Slugs azure, microsoft-azure und azure-* gehen zum selben Paket, und was es nicht enthält, scheitert mit FAIL anstatt auf eine Drittanbieter-Kopie zurückzufallen. Immer das azure/-Präfix für einen Dienst schreiben: ein reines cosmos durchläuft trotzdem die Drittanbieter-Kette. Microsoft Entra ID hat ein separates Icon-Set: die offizielle Datei als name=URL übergeben. Microsoft erlaubt diese Icons nur in Architekturdiagrammen, Schulungsmaterialien und Dokumentation. Niemals eines zuschneiden, spiegeln, drehen oder umformen, es nur für den Microsoft-Dienst verwenden, für den es steht, und das Paket sowie lose Icon-Dateien außerhalb von Repos halten.
• Azure-Diagramme behalten den normalen Stil mit Microsofts Gruppenfarben. Microsofts eigene Diagramme werden bewusst nicht kopiert: Icons kommen auf die normale weiße Kachel, und Kanten und 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 eigenes Icon (vnet:azure/vnet, subnet:azure/subnet). Ein VNet gehört zu einer Region, also kommt es innerhalb der Region. 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 Environment; ein PaaS-Dienst, der über einen privaten Endpunkt erreicht wird, kann darin sitzen, mit private endpoint als Rolle. Microsoft fordert 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).
• Kubernetes verwendet offizielle Community-Icons. Mit name:k8s/<Ressource> abrufen, aus dem offiziellen kubernetes/community-Icon-Set lesen (z.B. pod:k8s/pod, deploy:k8s/deployment, svc:k8s/service, ing:k8s/ingress, cm:k8s/configmap, secret:k8s/secret, node:k8s/node, api:k8s/kube-apiserver). Icons verwenden die unbeschrifteten Varianten für Ressourcen und Infrastruktur, um Glyphen sauber und übersichtlich zu halten, und beschriftete Varianten für Steuerungsebenen-Komponenten. Gängige Kurznamen und Plurale funktionieren (svc/service/services, deploy/deployment/deployments, po/pod/pods, cm/configmap/configmaps, sts/statefulset, ds/daemonset, node/nodes, etc.). Ein Fehltreffer gibt verfügbare Namen aus. Die Slugs k8s, kubernetes und k8s/k8s liefern das offizielle Kubernetes-Rad-Logo über die Kette.
• Kubernetes-Diagramme behalten standardmäßig den normalen Stil. Icons sitzen auf der normalen weißen Kachel, die sie mit anderen Technologien im Stack vereinheitlicht (wie NGINX, cert-manager, externe Datenbanken oder Cloud-Load-Balancer) und für konsistente Erhebung und Kontrast auf Graphpapier-Hintergründen sorgt. Für minimalistische eigenständige Glyphen wird auch tile bare unterstützt. Gruppen verwenden Standardgruppen (cluster, namespace, node, pod). Das Kubernetes-Icons-Set im Diagramm-Fußzeile nennen.
• Die Regeln eines Anbieters gelten nur für seinen eigenen Bereich. Die AWS-, Google Cloud-, Azure- und Kubernetes-Regeln gelten nur innerhalb der Gruppe des jeweiligen Anbieters, selbst wenn das Diagramm nichts anderes zeigt. Alles außerhalb, wie ein Benutzer daneben oder eine Kante, die hineinreicht, 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 Icon-Verzeichnis unter dem Knotennamen kopieren oder name:lucide/<icon> verwenden – kein Emoji. Dies sind keine Markenlogos, daher ist das Einfärben in die Diagramm-Tintenfarbe in Ordnung (das Abrufskript erledigt das für Lucide automatisch).
• Gruppenbeschriftungs-Icons werden mit 14px gerendert – sie benötigen eine quadratische Glyphenmarke. Wortmarken und breite Lockups werden bei dieser Größe matschig; 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 Theme 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 der Mark schwarze Teile hat, die Klasse plate zur Beschriftung hinzufügen.