hersaintel/stack-diagram

Que fait stack-diagram ?

Intégration Hermès

Résolvez <skill> dans le répertoire contenant ce SKILL.md, pas dans le répertoire de travail du projet. Exécutez les scripts fournis avec terminal via Python en utilisant des chemins absolus entre guillemets. Utilisez read_file pour les modèles/références et write_file/patch pour les artefacts. Privilégiez un environnement Python isolé pour Playwright ; une simple importation ne prouve pas que son pilote de navigateur fonctionne.

Pour les demandes basées sur un repository, enregistrez d'abord les preuves pour les nœuds et les arêtes. Les dépendances n'établissent pas la topologie d'exécution. Conservez les relations déduites étiquetées comme hypothèses ; demandez lorsque l'ambiguïté modifierait l'architecture. La topologie fournie explicitement par l'utilisateur est une preuve. Ne lisez jamais de secrets ou de fichiers non liés pour découvrir une pile.

Livrez les fichiers locaux en utilisant MEDIA:/chemin/absolu/vers/out.html et MEDIA:/chemin/absolu/vers/out.png (plus le PNG sombre) ; utilisez vision_analyze pour inspecter les deux thèmes rendus. Le HTML est la seule source de vérité visuelle ; les PNG proviennent de Chromium, pas d'un moteur de rendu SVG/PIL indépendant. Ne marquez pas un fichier comme livré avant qu'il n'existe. Cette compétence n'appelle ni ne modifie brag. Utilisez stack-video uniquement lorsqu'une vidéo est demandée ; c'est une compétence soeur indépendante, pas une étape obligatoire.

Les scripts/ressources en amont sont préservés de caru-ini/stack-diagram ; consultez le UPSTREAM.md de ce pack. Les instructions optionnelles de la galerie ci-dessous nécessitent toujours leur propre consentement explicite ; l'installation ou la publication de ce pack n'est pas un consentement pour la galerie.

Produit des diagrammes d'architecture de style dessin technique : logos réels sur des tuiles blanches, boîtes de groupe étiquetées (comme les diagrammes VPC des fournisseurs cloud), flèches orthogonales avec étiquettes monospace, sur un fond de papier quadrillé froid. Un seul fichier HTML autonome est la source de vérité ; les artefacts PNG/TSX en sont dérivés.

Prérequis

• Python 3.9+ (bibliothèque standard uniquement pour fetch_icons.py, build.py et share.py)
• Accès réseau aux sources d'icônes (svgl.app, raw.githubusercontent.com, cdn.jsdelivr.net, aws.amazon.com et d1.awsstatic.com pour les icônes AWS, services.google.com pour les icônes Google Cloud, learn.microsoft.com et arch-center.azureedge.net pour les icônes Azure, plus le site ou le repo de la marque pour nom=URL) lors de la récupération des icônes
• Playwright + Chromium pour render_png.py : pip install playwright && python3 -m playwright install --with-deps chromium

Flux de travail

1. Définissez le contenu (nœuds, groupes, arêtes)
2. Récupérez les icônes — scripts/fetch_icons.py
3. Planifiez les coordonnées — lisez references/geometry.md
4. Construisez le HTML à partir de assets/template.html — scripts/build.py
5. Générez un PNG et examinez-le avant de livrer
6. Livrez dans le(s) format(s) demandé(s)
7. Optionnellement, partagez-le dans la galerie publique

Étape 1 — Contenu

À partir de la liste des technologies/services fournie par l'utilisateur, décidez :

• Nœuds : chaque technologie = un nœud (nom + un court rôle en minuscules comme serveur http, db sqlite)
• Groupes : dessinez une boîte autour des éléments qui partagent un environnement d'exécution, un fournisseur ou un dépôt (par exemple, une boîte de fournisseur cloud contenant une boîte d'environnement d'exécution ; une boîte de monorepo pour les outils). Un niveau d'imbrication est acceptable ; plus profond devient bruyant. Écrivez les étiquettes de groupe dans la casse de la marque (GitHub, npm) ; le modèle les montre telles qu'écrites.
• Arêtes, trois types :
  • trait plein de couleur d'accent = le flux principal de requête/données (un chemin continu est le meilleur)
  • trait plein neutre = connexions internes secondaires
  • tirets neutres = relations de développement/déploiement (CI, hooks git, déploiement IaC)

Si l'utilisateur n'a donné qu'une liste plate d'outils, déduisez des groupes et des flux plausibles à partir de ce que sont les outils — ne demandez que lorsqu'un outil est suffisamment ambigu pour que le diagramme soit erroné dans les deux cas.

Étape 2 — Icônes

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

Formes de spécification : nom (nom utilisé comme slug), nom:slug (slug différent), nom=URL (URL explicite), nom:aws/<Nom> (icône AWS officielle), nom:gcp/<Produit> (icône Google Cloud officielle), nom:azure/<Nom> (icône Azure officielle). Le script essaie, dans l'ordre : svgl → devicon → gilbarbara/logos, écrit les fichiers plus manifest.json, et signale les icônes dont le remplissage est blanc. svgl (svgl.app) est premier car il porte les marques officielles actuelles pour les marques dev modernes (TanStack, Better Auth, Hono...). Lorsqu'un logo a des versions claire/sombre, la version claire devient <nom> (les tuiles sont blanches dans les deux thèmes) et la version sombre est enregistrée comme <nom>_dark pour les étiquettes de groupe. svgl est apparié uniquement par titre exact, donc un échec passe simplement au suivant. Son API expose aussi des variantes wordmark — parfois utiles pour une étiquette de groupe large, jamais pour les tuiles.

Règles qui importent plus que la mécanique :

• Ne jamais recolorer un logo. Les utilisateurs le remarquent. Si un logo est blanc ou trop clair pour une tuile blanche, placez-le sur une tuile sombre (classe tile dark) plutôt que de toucher à son remplissage. L'indicateur white_fill du manifeste est une heuristique — un remplissage blanc peut être un détail intérieur sur une marque colorée (tRPC, Ubuntu), donc jetez un coup d'œil au SVG avant de recourir à la tuile sombre.
• Marques officielles uniquement. simple-icons est délibérément pas une source : ses glyphes sont des redessins monochromes, et les utilisateurs les reconnaissent comme erronés au premier coup d'œil. Lorsque toutes les sources échouent (FAIL), trouvez le fichier officiel et passez-le comme nom=URL — cherchez dans le repo du projet (racine logo*.svg, docs/, assets/, public/) et sur son site (/logo.svg, /favicon.svg, /images/logo.svg). Certaines marques ne vivent que dans le repo (celle de Lefthook est logo_sign.svg à la racine de evilmartians/lefthook).
• Les concepts abstraits reçoivent des pictogrammes, pas du texte. Un nœud comme "environnement de dev", "cron", "file d'attente", "cache" ou "récepteur webhook" n'a pas de marque — utilisez une icône de ligne Lucide via nom:lucide/<icône> (par exemple devenv:lucide/terminal, cron:lucide/clock ; parcourez lucide.dev/icons). Pas de texte dans une tuile, pas d'émoji.
• Les sous-produits de fournisseur (Cloudflare D1/R2/KV...) n'ont généralement pas de logo distinct : réutilisez simplement le logo du fournisseur sur la tuile et laissez le nom du nœud porter la distinction ("Cloudflare D1" / "db sqlite").
• AWS utilise ses propres icônes. Chaque service en a une : récupérez-la avec nom:aws/<Nom>, lue depuis le pack d'icônes officiel AWS au moment de l'exécution (par exemple lambda:aws/lambda, aws:aws/AWS-Cloud-logo, s3:aws/s3). Le préfixe AWS- / Amazon- est optionnel, les acronymes courants fonctionnent (s3, sqs, sns, ses, ecs, eks, ecr, elb, alb, nlb, iam, kms, msk, vpc), et un échec imprime chaque nom. Les slugs aws, amazonwebservices et aws-* pointent vers le même pack, et ce qu'il ne contient pas génère un FAIL au lieu d'un repli vers une copie tierce. Écrivez toujours le préfixe aws/ pour un service : un dynamodb nu passe encore par la chaîne tierce. Gardez le pack et les fichiers d'icônes individuels hors des repos : AWS autorise les icônes dans les diagrammes, et la redistribution n'est pas confirmée.
• La zone AWS suit ses propres règles de dessin. Les icônes de service portent leur propre carré et fonctionnent sur fond clair et sombre, donc utilisez tile bare : une tuile blanche ne fait que doubler le cadre. Les personnes et les nœuds génériques à l'intérieur utilisent les icônes générales AWS (utilisateur:aws/General-User ; aussi General-Users, General-Client, General-Internet, General-Server) en tile bare res avec la paire lt/dk du modèle. Les groupes utilisent le group aws du modèle pour AWS Cloud (avec aws:aws/AWS-Cloud-logo dans l'étiquette), plus region, az, vpc, private ou public pour le reste : coins carrés, contour uniquement, étiquette à l'encre, pas de teinte de fournisseur, et une icône de 30px encastrée dans le coin au lieu de celle de 14px. À l'intérieur d'un VPC, montrez les sous-réseaux publics et privés lorsque vous connaissez ou pouvez déduire en toute sécurité la répartition (un équilibreur de charge orienté Internet en public ; les serveurs d'application et les bases de données en privé) : un VPC plat est la première chose que les utilisateurs AWS remarquent. Les arêtes à l'intérieur utilisent une seule couleur et une pointe de flèche ouverte : <path class="aws" ... marker-end="url(#open)"/>, aws dash pour dév/déploiement, étiquettes .el simples, et pas de légende pour elles. Nommez les nœuds Amazon S3 / AWS Fargate, pas un S3 / Fargate nu ; une forme courte comme ALB va dans la ligne de rôle, sous le nom complet (Elastic Load Balancing). Les noms peuvent prendre deux lignes, mais Amazon / AWS doivent rester sur la ligne du premier mot : s'il y a un retour à la ligne juste après le préfixe, élargissez ce nœud (left:<centerX-76>px; width:152px).
• Google Cloud utilise ses propres icônes. Récupérez-les avec nom:gcp/<Produit>, lues depuis les packs officiels Google au moment de l'exécution (par exemple run:gcp/cloud-run, lb:gcp/load-balancing, memorystore:gcp/memorystore). Seuls les produits principaux ont leur propre icône (Cloud Run, Cloud SQL, Cloud Storage, BigQuery, GKE, Compute Engine, Vertex AI...). Chaque autre produit utilise l'icône de sa catégorie, comme le spécifie le guide de Google : Cloud Load Balancing et Cloud CDN obtiennent tous deux Networking, Memorystore et Firestore obtiennent tous deux Databases. Écrivez le nom du produit et le script choisit l'icône. Le préfixe Cloud / Google est optionnel, certaines formes courtes fonctionnent (vpc, iam, kms, iap, gce, gcs), et un échec imprime chaque nom. gcp/storage est la catégorie Storage ; Cloud Storage est gcp/cloud-storage. Les slugs gcp-* et google-cloud-* pointent vers les mêmes packs, et ce qu'ils ne contiennent pas génère un FAIL au lieu d'un repli vers une copie tierce : ces copies sont les icônes hexagonales retirées, que Google dit de ne pas utiliser. Écrivez toujours le préfixe gcp/ pour un produit : un bigquery nu passe encore par la chaîne tierce. gcp:google-cloud est la marque Google Cloud pour l'étiquette de groupe. Gemini et Firebase ne sont pas dans les packs : utilisez gemini et firebase nus. Gardez les packs et les fichiers d'icônes individuels hors des repos : Google offre les icônes pour les diagrammes et la documentation, et la redistribution n'est pas confirmée.
• Les diagrammes Google Cloud conservent le style normal, avec les groupes de Google. Les diagrammes propres à Google (panneau bleu uni, cartes horizontales) ne sont délibérément pas copiés : les icônes vont sur la tuile blanche normale, et les arêtes et la légende restent comme d'habitude. Les groupes utilisent le group gcp du modèle pour Google Cloud (avec gcp:google-cloud dans l'étiquette), plus vpc, region, subnet ou zone. Un VPC est global et un sous-réseau est régional, donc placez la région à l'intérieur du VPC, jamais le VPC à l'intérieur d'une région. Les services globaux et sans serveur (un équilibreur de charge externe, Cloud Storage, Cloud Run) restent en dehors du VPC. Parce que les icônes sont partagées, écrivez toujours le nom complet du produit (Cloud Load Balancing, pas LB), et élargissez un nœud dont le nom serait coupé (left:<centerX-76>px; width:152px).
• Azure utilise ses propres icônes Microsoft. Chaque service en a une : récupérez-la avec nom:azure/<Nom>, lue depuis le pack officiel Microsoft au moment de l'exécution (par exemple app:azure/app-service, azure:azure/Azure-A, vault:azure/key-vault). Le préfixe Azure- / Microsoft- et un s pluriel sont optionnels, les formes courtes courantes fonctionnent (aks, vm, vnet, nsg, waf, blob, cosmos, redis, postgres, functions, front-door, apim, ai-search), et un échec imprime chaque nom. Les slugs azure, microsoft-azure et azure-* pointent vers le même pack, et ce qu'il ne contient pas génère un FAIL au lieu d'un repli vers une copie tierce. Écrivez toujours le préfixe azure/ pour un service : un cosmos nu passe encore par la chaîne tierce. Microsoft Entra ID a un set d'icônes séparé : passez son fichier officiel comme nom=URL. Microsoft autorise ces icônes uniquement dans les diagrammes d'architecture, les supports de formation et la documentation. Ne recadrez, ne retournez, ne faites pas pivoter ou ne changez pas la forme d'une icône, utilisez-la uniquement pour le service Microsoft qu'elle représente, et gardez le pack et les fichiers d'icônes individuels hors des repos.
• Les diagrammes Azure conservent le style normal, avec les couleurs de groupe de Microsoft. Les diagrammes propres à Microsoft ne sont délibérément pas copiés : les icônes vont sur la tuile blanche normale, et les arêtes et la légende restent comme d'habitude. Les groupes utilisent le group azure du modèle pour Azure (avec azure:azure/Azure-A dans l'étiquette), plus rg, region, vnet, subnet ou zone, et une étiquette vnet ou subnet porte son icône (vnet:azure/vnet, subnet:azure/subnet). Un VNet appartient à une région, donc il va à l'intérieur de la région. Les services globaux comme Front Door restent en dehors de la région. App Service se trouve en dehors du VNet sauf s'il s'exécute dans un App Service Environment, et un service PaaS atteint via un point de terminaison privé peut se trouver à l'intérieur avec private endpoint comme rôle. Microsoft demande le nom complet du service à côté de chaque icône (Azure SQL Database, pas SQL), donc élargissez un nœud dont le nom serait coupé (left:<centerX-76>px; width:152px).
• Les règles d'un fournisseur ne couvrent que sa propre zone. Les règles AWS, Google Cloud et Azure s'appliquent uniquement à l'intérieur du groupe de ce fournisseur, même si le diagramme ne montre rien d'autre. Tout ce qui est en dehors, comme un utilisateur à côté ou une arête qui le traverse, conserve les tuiles, groupes, arêtes et légende normaux.
• Nœuds non-marque (utilisateur, navigateur, internet, appareils, serveur nu) : copiez un glyphe depuis assets/generic/ dans le répertoire des icônes sous le nom du nœud, ou utilisez nom:lucide/<icône> — n'utilisez pas d'émoji. Ce ne sont pas des logos de marque, donc les teinter à la couleur d'encre du diagramme est acceptable (le script de récupération le fait automatiquement pour Lucide).
• Les icônes d'étiquette de groupe sont rendues à 14px — elles ont besoin d'une marque de glyphe carrée. Les wordmarks et les grandes compositions deviennent boueuses à cette taille ; si l'icône principale est un wordmark, récupérez l'icône carrée de la marque séparément pour l'étiquette (svgl l'a généralement ; sinon le fichier icône ou favicon du projet).
• Les étiquettes de groupe reposent sur la teinte du groupe, pas sur une tuile blanche, donc dans le thème sombre, une marque avec des parties noires y disparaît. Si fetch_icons.py a enregistré <nom>_dark, utilisez la paire lt/dk du modèle dans l'étiquette ; s'il n'y a pas de variante sombre et que la marque a des parties noires, ajoutez la classe plate au <img> de l'étiquette (fond blanc, thème sombre uniquement).
• Les logos raster (png/webp) sont acceptables ; le build les convertit en base64 dans le HTML.

Étape 3 — Coordonnées

Lisez references/geometry.md pour les constantes de disposition. Le plan de coordonnées du diagramme est une feuille de papier de 1 000x800 px avec une zone de dessin interne après la légende. Les nœuds ont width:76px; height:76px. Les groupes de tuiles sont alignés sur une grille, espacés de 14px. Le coin inférieur droit est réservé aux pointeurs : height:30px à partir du bas. Les étiquettes ".el" utilisent la classe label el et sont écrites au-dessus des arêtes avec transform: translate(dx, dy). Les étiquettes ".r" (rôle) sont écrites sous les nœuds avec transform: translate(-20, 30). Soit .el soit .r reçoit un rect de fond de teinte — pas les deux. L'outil est dans ES Module ; toute version récente de Node.js lira les fichiers ESM sans --experimental-vm-modules.

Étape 4 — Construction

python3 scripts/build.py <fichier-contenu> <répertoire-icônes> <sortie.html>

Lit un fichier JSON de contenu avec les nœuds, groupes et arêtes. Chaque nœud spécifie name, role, icon, plus optionnellement width (pour les noms longs) et tile (bare, bare res, dark). Les groupes listent les nœuds enfants et optionnellement subgroup. Les arêtes listent from et to (IDs de nœuds), label, type (primary, secondary, dashed), et optionnellement class (aws). Utilisez write_file ou patch pour écrire le rendu ou modifier une version précédente.

Étape 5 — Rendu

python3 scripts/render_png.py <entrée.html> <sortie.png> [--dark] [width=1200]

Utilise Playwright avec Chromium pour rendre le HTML comme un navigateur le ferait. Portée : le diagramme d'architecture complet, pas la page entière. vision_analyze sur la sortie inspecte les deux thèmes. Le HTML est seul responsable de la mise en page ; le PNG est une copie exacte. Lorsque le HTML incluait une image raster, vérifiez qu'elle n'est pas floue — le redimensionnement CSS peut produire un PNG flou. La largeur par défaut est 1 200 px, assez large pour les diagrammes multi-vendeurs. Ajustez à 1 600 px si le diagramme est plus grand que 1 000x800.

Étape 6 — Livraison

Livrez out.html et out.png avec des chemins MEDIA:. Incluez out_dark.png. Le HTML est la seule source de vérité ; les PNG sont des vues dérivées. Fournissez des artefacts supplémentaires (TSX pour le composant React, SVG/CANVAS) uniquement sur demande.

Étape 7 — Galerie

python3 scripts/share.py <fichier.html> [--title "Titre"] [--author "Auteur"] [--description "Description"]

Ne partagez que lorsque l'utilisateur demande explicitement une galerie publique ("publie-le", "ajoute à la galerie", "partage-le"). Ne partagez pas les diagrammes avec des secrets, des topologies clientes ou des données propriétaires. La galerie est publique : tout le monde peut voir et utiliser les diagrammes que vous partagez. Les fichiers partagés sont définitifs ; aucune suppression n'est possible sans contacter les mainteneurs. Utilisez script ou terminal avec le répertoire de travail défini sur <skill>/ (le répertoire du pack) pour exécuter share.py.