lookbkdev/blueprint-architecture

Diagramme d'Architecture Blueprint

Un système dessiné comme une feuille d'ingénierie : un blueprint quadrillé (ou un « whiteprint » clair), chaque composant sous forme de forme étiquetée selon son type, des flèches pour les requêtes et des flèches en pointillés pour les événements, des zones en pointillés pour les groupes, une légende et un cartouche. Vous (ou la personne) décrivez le système sous forme de diagram.json ; un script le dispose avec dagre (intégré, rien à installer) et dessine :

• out/index.html : le diagramme avec un point voyageant le long de chaque connexion et des lignes d'événements qui coulent. S'ouvre depuis le disque, s'adapte à la fenêtre.
• out/diagram.svg : le même dessin sans animation, pour la documentation, les wikis et les diapositives.
• out/diagram.png : une image fixe au double de la taille, générée avec Chrome sans tête, pour les images partout.

Prérequis

• Node.js 18 ou plus récent. La génération ne nécessite rien d'autre.
• Chrome, Chromium ou Edge pour le PNG. Le script le trouve dans les emplacements habituels ; définissez CHROME_PATH s'il ne le trouve pas.
• Accès Internet lorsque le diagramme est ouvert ou exporté, pour la police JetBrains Mono depuis Google Fonts (elle est remplacée par la police monospace système sans cela).

Le dossier de cette compétence est <skill> ci-dessous : le dossier où se trouve ce SKILL.md.

Étapes

1. Trouver le système

Lorsque la personne décrit le système, utilisez ses mots. Lorsqu'on vous demande de lire un dépôt, rassemblez les preuves avant de dessiner quoi que ce soit et ne dessinez que ce que vous avez trouvé :

1. Déployables : services docker-compose*.yml, Deployments Kubernetes, Helm charts, Procfiles, configurations serverless (serverless.yml, vercel.json, wrangler.toml), ressources Terraform et applications dans un monorepo (apps/, services/, packages/* avec un script de démarrage).
2. Stores de données et courtiers : images et ressources gérées (postgres, mysql, mongo, redis, kafka, rabbitmq, sqs, s3), et paramètres de connexion comme DATABASE_URL, REDIS_URL, KAFKA_BROKERS, noms de buckets.
3. Connexions : clients HTTP et URL de base pointant vers d'autres services, stubs gRPC, producteurs et consommateurs de files d'attente (noms de topics et de files), depends_on, appels sortants vers des tiers (Stripe, une API LLM, fournisseurs de messagerie).
4. Appelants : applications web et mobiles, CLI, tâches cron, webhooks.

Conservez entre 5 et 20 nœuds. Fusionnez les réplicas et les petits assistants dans le service auquel ils appartiennent ; divisez en plusieurs feuilles ("sheet": "02 / 03") plutôt que de tasser. Notez tout ce que vous avez déduit plutôt que trouvé, et informez la personne.

2. Écrire diagram.json

{
  "title": "Service commandes · v2",
  "subtitle": "Architecture système · depuis /services et docker-compose.yml · 21 oct. 2026",
  "sheet": "01 / 01",
  "direction": "LR",
  "theme": "blueprint",
  "groups": [{ "id": "core", "label": "Plateforme commandes" }],
  "nodes": [
    {
      "id": "gateway",
      "label": "Passerelle API",
      "sub": "auth · limite de débit",
      "kind": "service"
    },
    {
      "id": "orders",
      "label": "Service commandes",
      "sub": "v2 · Go · 6 pods",
      "kind": "service",
      "group": "core",
      "focus": true
    },
    {
      "id": "db",
      "label": "Postgres",
      "sub": "commandes · stock",
      "kind": "database"
    },
    {
      "id": "bus",
      "label": "Bus d'événements",
      "sub": "Kafka · 3 topics",
      "kind": "queue"
    }
  ],
  "edges": [
    { "from": "gateway", "to": "orders", "label": "POST /orders" },
    { "from": "orders", "to": "db", "label": "SQL" },
    { "from": "orders", "to": "bus", "label": "order.created", "async": true }
  ]
}

Champ	Description	Limite
title	Nom du système ou de la vue (obligatoire) ; apparaît également dans le cartouche	60
subtitle	Ce que montre le dessin et d'où il vient : sources et date	100
sheet	Numéro de feuille dans le cartouche, ex. "02 / 03" (par défaut 01 / 01)	–
direction	LR de gauche à droite (par défaut, adapté aux flux de requêtes) ou TB de haut en bas (pipelines)	–
theme	blueprint (bleu foncé, par défaut), whiteprint (clair), ou couleurs : { "paper", "line", "accent", "dim" } en hexadécimal	–
groups	Zones dessinées autour de leurs nœuds : { "id", "label" }	–
nodes[].id	Lettres, chiffres, - ou _ ; les arêtes y font référence (obligatoire)	–
nodes[].label	Nom du nœud (obligatoire)	28
nodes[].sub	Deuxième ligne : langage, runtime, échelle, ce qu'il contient	36
nodes[].kind	Forme : service (par défaut), client, database, queue, cache, storage, function, external (tiers, en pointillé)	–
nodes[].group	Un identifiant de groupe	–
nodes[].focus	true le dessine dans la couleur d'accent : l'élément central du diagramme	–
edges[]	{ "from", "to" } identifiants de nœuds, dans le sens du flux de données ou de contrôle	–
edges[].label	Protocole, point de terminaison, topic ou verbe : HTTPS, POST /orders, order.created	24
edges[].async	true pour les événements, files d'attente et tout ce qui est « fire-and-forget » (pointillé, animé)	–

Conseils :

• Étiquetez les arêtes avec ce qui voyage réellement : un point de terminaison, un topic, une table, un verbe. Omettez une étiquette uniquement si elle n'apporte rien.
• Orientez les arêtes dans le sens des requêtes (appelant vers appelé) et des événements (producteur vers file puis consommateur).
• Au maximum, marquez un seul nœud focus.
• Jusqu'à 40 nœuds sont autorisés, mais au-delà d'environ 20, le dessin devient difficile à lire.

3. Générer et vérifier

node <skill>/scripts/build.mjs diagram.json out

Il vérifie le fichier et liste chaque problème en une fois (une arête vers un nœud qui n'existe pas, une étiquette dépassant sa limite), puis écrit out/index.html et out/diagram.svg. Ouvrez out/index.html et vérifiez :

• tous les nœuds de l'étape 1 sont présents, et rien que vous n'ayez pas trouvé,
• les arêtes pointent dans le bon sens et leurs étiquettes sont lisibles,
• les groupes contiennent les bons nœuds.

Si la disposition est enchevêtrée, essayez l'autre direction, ou réordonnez nodes et edges : la disposition commence à partir de leur ordre.

4. Exporter le PNG

node <skill>/scripts/export-png.mjs out/index.html

Il écrit out/diagram.png au double de la taille du dessin ; ajoutez --scale=1 pour la taille réelle.

5. Remettre le résultat

Donnez à la personne out/index.html (animé), out/diagram.svg et out/diagram.png, ainsi que diagram.json pour que le dessin puisse être mis à jour lorsque le système change : modifiez le JSON et exécutez à nouveau les étapes 3 et 4. Si le diagramme doit faire partie du dépôt, un dossier docs/architecture/ contenant le JSON et le SVG est un bon emplacement ; le SVG s'affiche dans GitHub et la plupart des wikis.

Dépannage

• build: fix diagram.json first : chaque ligne nomme le nœud ou l'arête et ce qui doit être modifié.
• L'étape PNG indique qu'aucun Chrome n'a été trouvé : définissez CHROME_PATH, ou ouvrez out/index.html et faites une capture d'écran.
• Le texte est dans une police monospace différente : la page n'a pas pu accéder à Google Fonts. Installez JetBrains Mono (gratuit) pour correspondre hors ligne.
• Les arêtes se croisent beaucoup : changez direction, déplacez le nœud qui s'emmêle plus tôt ou plus tard dans nodes, ou divisez le système en deux feuilles.

Fichiers

• scripts/build.mjs : vérifie diagram.json, le dispose et dessine le HTML et le SVG. Aucune dépendance à installer.
• scripts/export-png.mjs : enregistre le PNG avec Chrome sans tête.
• vendor/dagre.esm.js : la bibliothèque de disposition de graphes dagre (MIT), intégrée pour ne rien avoir à installer ; sa licence est dans vendor/LICENSE-dagre.txt.
• examples/order-service/ (blueprint, de gauche à droite) et examples/rag-pipeline/ (whiteprint, de haut en bas) : fichiers diagram.json complets. Les aperçus sur Lookbk sont générés à partir de ceux-ci.
• NOTICE.md : logiciels tiers et polices utilisés par cette compétence.