lookbkdev/blueprint-architecture

Diagrama de Arquitetura Blueprint

Um sistema desenhado como uma folha de engenharia: um blueprint quadriculado (ou um "whiteprint" claro), cada componente como uma forma rotulada por tipo, setas para requisições e setas tracejadas para eventos, zonas tracejadas para grupos, uma legenda e um bloco de título. Você (ou a pessoa) descreve o sistema como diagram.json; um script o posiciona com dagre (incluído, nada para instalar) e desenha:

• out/index.html: o diagrama com um ponto viajando por cada conexão e as linhas de evento fluindo. Abre do disco, escala para a janela.
• out/diagram.svg: o mesmo desenho sem movimento, para docs, wikis e slides.
• out/diagram.png: uma imagem estática com o dobro do tamanho, renderizada com Chrome headless, para qualquer lugar onde imagens são necessárias.

O que você precisa

• Node.js 18 ou superior. A construção não precisa de mais nada.
• Chrome, Chromium ou Edge para o PNG. O script o encontra nos locais comuns; defina CHROME_PATH se não encontrar.
• Acesso à internet quando o diagrama for aberto ou exportado, para a fonte JetBrains Mono do Google Fonts (ela usa a fonte monoespaçada do sistema como fallback sem ela).

A pasta desta skill é <skill> abaixo: a pasta onde este SKILL.md está.

Passos

1. Encontre o sistema

Quando a pessoa descreve o sistema, use as palavras dela. Quando for solicitado a ler um repositório, reúna evidências antes de desenhar qualquer coisa, e desenhe apenas o que encontrou:

1. Implmentáveis: serviços docker-compose*.yml, Deployment do Kubernetes, Helm charts, Procfiles, configurações serverless (serverless.yml, vercel.json, wrangler.toml), recursos Terraform e apps em um monorepo (apps/, services/, packages/* com um script de inicialização).
2. Armazenamentos e barramentos: imagens e recursos gerenciados (postgres, mysql, mongo, redis, kafka, rabbitmq, sqs, s3) e configurações de conexão como DATABASE_URL, REDIS_URL, KAFKA_BROKERS, nomes de buckets.
3. Conexões: clientes HTTP e URLs base apontando para outros serviços, stubs gRPC, produtores e consumidores de filas (nomes de tópicos e filas), depends_on, chamadas externas para terceiros (Stripe, uma API de LLM, provedores de email).
4. Chamadores: aplicativos web e mobile, CLIs, cron jobs, webhooks.

Mantenha de 5 a 20 nós. Mescle réplicas e ajudantes pequenos no serviço ao qual pertencem; divida em várias folhas ("sheet": "02 / 03") em vez de amontoar. Anote qualquer coisa que deduziu em vez de encontrou, e informe a pessoa.

2. Escreva diagram.json

{
  "title": "Serviço de pedidos · v2",
  "subtitle": "Arquitetura do sistema · de /services e docker-compose.yml · 21 Out 2026",
  "sheet": "01 / 01",
  "direction": "LR",
  "theme": "blueprint",
  "groups": [{ "id": "core", "label": "Plataforma de pedidos" }],
  "nodes": [
    {
      "id": "gateway",
      "label": "API gateway",
      "sub": "auth · limite de taxa",
      "kind": "service"
    },
    {
      "id": "orders",
      "label": "Serviço de pedidos",
      "sub": "v2 · Go · 6 pods",
      "kind": "service",
      "group": "core",
      "focus": true
    },
    {
      "id": "db",
      "label": "Postgres",
      "sub": "pedidos · estoque",
      "kind": "database"
    },
    {
      "id": "bus",
      "label": "Barramento de eventos",
      "sub": "Kafka · 3 tópicos",
      "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	O que é	Limite
title	Nome do sistema ou visão (obrigatório); também vai no bloco de título	60
subtitle	O que o desenho mostra e de onde veio: fontes e data	100
sheet	Número da folha no bloco de título, ex. "02 / 03" (padrão 01 / 01)	–
direction	LR esquerda para direita (padrão, adequado para fluxos de requisição) ou TB cima para baixo (pipelines)	–
theme	blueprint (azul escuro, padrão), whiteprint (claro), ou cores: { "paper", "line", "accent", "dim" } como hex	–
groups	Zonas desenhadas ao redor de seus nós: { "id", "label" }	–
nodes[].id	Letras, dígitos, - ou _; as arestas se referem a ele (obrigatório)	–
nodes[].label	Nome no nó (obrigatório)	28
nodes[].sub	Segunda linha: linguagem, runtime, escala, o que contém	36
nodes[].kind	Forma: service (padrão), client, database, queue, cache, storage, function, external (terceiros, tracejado)	–
nodes[].group	Um id de grupo	–
nodes[].focus	true desenha na cor de destaque: a coisa sobre a qual o diagrama é	–
edges[]	{ "from", "to" } ids de nós, na direção que os dados ou o controle fluem	–
edges[].label	Protocolo, endpoint, tópico ou verbo: HTTPS, POST /orders, order.created	24
edges[].async	true para eventos, filas e qualquer coisa fire-and-forget (tracejado, fluindo)	–

Dicas:

• Rotule as arestas com o que realmente viaja: um endpoint, um tópico, uma tabela, um verbo. Deixe um rótulo de fora apenas quando não agregar nada.
• Aponte as arestas no sentido das requisições (chamador para chamado) e dos eventos (produtor para fila para consumidor).
• Marque no máximo um nó como focus.
• Até 40 nós são permitidos, mas depois de cerca de 20 o desenho fica difícil de ler.

3. Construa e verifique

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

Ele verifica o arquivo e lista todos os problemas de uma vez (uma aresta para um nó que não existe, um rótulo acima do limite), então escreve out/index.html e out/diagram.svg. Abra out/index.html e verifique:

• cada nó do passo 1 está lá, e nada que você não encontrou,
• as arestas apontam na direção correta e seus rótulos são legíveis,
• os grupos contêm os nós corretos.

Se o layout estiver embaralhado, tente a outra direction, ou reordene nodes e edges: o layout começa a partir de sua ordem.

4. Exporte o PNG

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

Ele escreve out/diagram.png com o dobro do tamanho do desenho; adicione --scale=1 para o tamanho real.

5. Entregue

Entregue para a pessoa out/index.html (animado), out/diagram.svg e out/diagram.png, além de diagram.json para que o desenho possa ser atualizado quando o sistema mudar: edite o JSON e execute os passos 3 e 4 novamente. Se o diagrama pertencer ao repositório, uma pasta docs/architecture/ com o JSON e o SVG é um bom lugar; o SVG renderiza no GitHub e na maioria dos wikis.

Solução de problemas

• build: fix diagram.json first: cada linha nomeia o nó ou aresta e o que alterar.
• A etapa do PNG diz que nenhum Chrome foi encontrado: defina CHROME_PATH, ou abra out/index.html e tire um print.
• O texto está em uma fonte monoespaçada diferente: a página não conseguiu acessar o Google Fonts. Instale JetBrains Mono (gratuita) para corresponder offline.
• As arestas se cruzam muito: mude direction, mova o nó que está embaralhado para mais cedo ou mais tarde em nodes, ou divida o sistema em duas folhas.

Arquivos

• scripts/build.mjs: verifica diagram.json, posiciona e desenha o HTML e SVG. Sem dependências para instalar.
• scripts/export-png.mjs: salva o PNG com Chrome headless.
• vendor/dagre.esm.js: a biblioteca de layout de gráfico dagre (MIT), incluída para que nada precise ser instalado; sua licença está em vendor/LICENSE-dagre.txt.
• examples/order-service/ (blueprint, esquerda para direita) e examples/rag-pipeline/ (whiteprint, cima para baixo): arquivos diagram.json completos. As prévias no Lookbk são desenhadas a partir deles.
• NOTICE.md: software de terceiros e fontes que esta skill usa.