lookbkdev/blueprint-architecture

Diagrama de Arquitectura Blueprint

Un sistema dibujado como una lámina de ingeniería: un plano cuadriculado (o un "whiteprint" claro), cada componente como una forma etiquetada según su tipo, flechas para solicitudes y flechas discontinuas para eventos, zonas punteadas para grupos, una leyenda y un bloque de título. Tú (o la persona) describen el sistema como diagram.json; un script lo dispone con dagre (incluido, sin nada que instalar) y dibuja:

• out/index.html: el diagrama con un punto que viaja a lo largo de cada conexión y las líneas de eventos fluyendo. Se abre desde el disco, se escala a la ventana.
• out/diagram.svg: el mismo dibujo sin movimiento, para documentación, wikis y diapositivas.
• out/diagram.png: una imagen estática al doble de tamaño, desde Chrome sin cabeza, para cualquier lugar donde vayan las imágenes.

Qué necesitas

• Node.js 18 o más reciente. La construcción no necesita nada más.
• Chrome, Chromium o Edge para el PNG. El script lo encuentra en los lugares habituales; establece CHROME_PATH si no lo encuentra.
• Acceso a Internet cuando el diagrama se abre o se exporta, para la fuente JetBrains Mono de Google Fonts (vuelve a la fuente monoespaciada del sistema sin ella).

La carpeta de esta habilidad es <skill> a continuación: la carpeta donde está este SKILL.md.

Pasos

1. Encuentra el sistema

Cuando la persona describe el sistema, usa sus palabras. Cuando te pidan leer un repositorio, recopila evidencia antes de dibujar cualquier cosa, y dibuja solo lo que encontraste:

1. Desplegables: servicios de docker-compose*.yml, Deployments de Kubernetes, Helm charts, Procfiles, configuraciones serverless (serverless.yml, vercel.json, wrangler.toml), recursos de Terraform y aplicaciones en un monorepo (apps/, services/, packages/* con un script de inicio).
2. Almacenes de datos y brokers: imágenes y recursos gestionados (postgres, mysql, mongo, redis, kafka, rabbitmq, sqs, s3), y configuraciones de conexión como DATABASE_URL, REDIS_URL, KAFKA_BROKERS, nombres de buckets.
3. Conexiones: clientes HTTP y URLs base que apuntan a otros servicios, stubs gRPC, productores y consumidores de colas (nombres de tópicos y colas), depends_on, llamadas salientes a terceros (Stripe, una API de LLM, proveedores de correo).
4. Llamantes: aplicaciones web y móviles, CLIs, cron jobs, webhooks.

Mantén de 5 a 20 nodos. Fusiona réplicas y ayudantes pequeños en el servicio al que pertenecen; divide en varias hojas ("sheet": "02 / 03") en lugar de amontonar. Anota cualquier cosa que hayas inferido en lugar de encontrado, e informa a la persona.

2. Escribe diagram.json

{
  "title": "Order service · v2",
  "subtitle": "System architecture · from /services and docker-compose.yml · 21 Oct 2026",
  "sheet": "01 / 01",
  "direction": "LR",
  "theme": "blueprint",
  "groups": [{ "id": "core", "label": "Order platform" }],
  "nodes": [
    {
      "id": "gateway",
      "label": "API gateway",
      "sub": "auth · rate limit",
      "kind": "service"
    },
    {
      "id": "orders",
      "label": "Order service",
      "sub": "v2 · Go · 6 pods",
      "kind": "service",
      "group": "core",
      "focus": true
    },
    {
      "id": "db",
      "label": "Postgres",
      "sub": "orders · stock",
      "kind": "database"
    },
    {
      "id": "bus",
      "label": "Event bus",
      "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 }
  ]
}

Campo	Qué es	Límite
title	Nombre del sistema o vista (obligatorio); también va en el bloque de título	60
subtitle	Qué muestra el dibujo y de dónde proviene: fuentes y fecha	100
sheet	Número de hoja en el bloque de título, ej. "02 / 03" (por defecto 01 / 01)	–
direction	LR izquierda a derecha (por defecto, adecuado para flujos de solicitud) o TB arriba a abajo (tuberías)	–
theme	blueprint (azul oscuro, por defecto), whiteprint (claro), o colores: { "paper", "line", "accent", "dim" } como hex	–
groups	Zonas dibujadas alrededor de sus nodos: { "id", "label" }	–
nodes[].id	Letras, dígitos, - o _; los bordes se refieren a él (obligatorio)	–
nodes[].label	Nombre en el nodo (obligatorio)	28
nodes[].sub	Segunda línea: lenguaje, tiempo de ejecución, escala, lo que contiene	36
nodes[].kind	Forma: service (por defecto), client, database, queue, cache, storage, function, external (tercero, discontinuo)	–
nodes[].group	Un id de grupo	–
nodes[].focus	true lo dibuja en el color de acento: la cosa sobre la que trata el diagrama	–
edges[]	{ "from", "to" } ids de nodo, en la dirección del flujo de datos o control	–
edges[].label	Protocolo, endpoint, tópico o verbo: HTTPS, POST /orders, order.created	24
edges[].async	true para eventos, colas y cualquier cosa de fuego y olvido (discontinuo, fluyendo)	–

Consejos:

• Etiqueta los bordes con lo que realmente viaja: un endpoint, un tópico, una tabla, un verbo. Omite una etiqueta solo cuando no añada nada.
• Apunta los bordes en la dirección en que van las solicitudes (llamante a llamado) y los eventos (productor a cola a consumidor).
• Marca como máximo un nodo con focus.
• Se permiten hasta 40 nodos, pero a partir de unos 20 el dibujo se vuelve difícil de leer.

3. Construye y verifica

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

Verifica el archivo y enumera cada problema de una vez (un borde a un nodo que no existe, una etiqueta sobre su límite), luego escribe out/index.html y out/diagram.svg. Abre out/index.html y verifica:

• cada nodo del paso 1 está ahí, y nada que no hayas encontrado,
• los bordes apuntan en la dirección correcta y sus etiquetas son legibles,
• los grupos contienen los nodos correctos.

Si el diseño está enredado, prueba la otra direction, o reordena nodes y edges: el diseño comienza desde su orden.

4. Exporta el PNG

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

Escribe out/diagram.png al doble del tamaño del dibujo; añade --scale=1 para el tamaño real.

5. Entrégalo

Entrega a la persona out/index.html (animado), out/diagram.svg y out/diagram.png, además de diagram.json para que el dibujo pueda actualizarse cuando el sistema cambie: edita el JSON y ejecuta los pasos 3 y 4 de nuevo. Si el diagrama pertenece al repositorio, una carpeta docs/architecture/ con el JSON y el SVG es un buen lugar; el SVG se renderiza en GitHub y en la mayoría de wikis.

Solución de problemas

• build: fix diagram.json first: cada línea nombra el nodo o borde y qué cambiar.
• El paso PNG dice que no se encontró Chrome: establece CHROME_PATH, o abre out/index.html y haz una captura de pantalla.
• El texto está en una fuente monoespaciada diferente: la página no pudo alcanzar Google Fonts. Instala JetBrains Mono (gratuita) para que coincida sin conexión.
• Los bordes se cruzan mucho: cambia direction, mueve el nodo que está enredado antes o después en nodes, o divide el sistema en dos hojas.

Archivos

• scripts/build.mjs: verifica diagram.json, lo diseña y dibuja el HTML y SVG. Sin dependencias que instalar.
• scripts/export-png.mjs: guarda el PNG con Chrome sin cabeza.
• vendor/dagre.esm.js: la librería de diseño de grafos dagre (MIT), incluida para que no sea necesario instalar nada; su licencia está en vendor/LICENSE-dagre.txt.
• examples/order-service/ (blueprint, izquierda a derecha) y examples/rag-pipeline/ (whiteprint, arriba a abajo): archivos diagram.json terminados. Las vistas previas en Lookbk se dibujan a partir de estos.
• NOTICE.md: software y fuentes de terceros que utiliza esta habilidad.