hersaintel/stack-diagram

O que stack-diagram faz?

Integração com Hermes

Resolva <skill> para o diretório que contém este SKILL.md, não o diretório de trabalho do projeto. Execute scripts empacotados com terminal via Python usando caminhos absolutos entre aspas. Use read_file para templates/referências e write_file/patch para artefatos. Prefira um ambiente Python isolado para Playwright; uma importação sozinha não prova que o driver do navegador funciona.

Para solicitações baseadas em repositório, registre evidências para nós e arestas primeiro. Dependências não estabelecem topologia de execução. Mantenha relacionamentos inferidos rotulados como suposições; pergunte quando a ambiguidade alteraria a arquitetura. Topologia fornecida explicitamente pelo usuário é evidência. Nunca leia segredos ou arquivos não relacionados para descobrir uma pilha.

Entregue arquivos locais usando MEDIA:/caminho/absoluto/para/out.html e MEDIA:/caminho/absoluto/para/out.png (mais o PNG escuro); use vision_analyze para inspecionar ambos os temas renderizados. HTML é a única fonte visual da verdade; PNGs vêm do Chromium, não de um renderizador SVG/PIL independente. Não marque um arquivo como entregue antes de ele existir. Esta skill não chama ou modifica o brag. Use stack-video apenas quando um vídeo for solicitado; é um skill irmão independente, não uma etapa obrigatória.

Scripts/recursos upstream são preservados do caru-ini/stack-diagram; veja o UPSTREAM.md deste pacote. As instruções opcionais da galeria ainda exigem seu próprio consentimento explícito; instalar ou publicar este pacote não é consentimento da galeria.

Produz diagramas de arquitetura em estilo de desenho técnico: logos reais em blocos brancos, caixas de grupo rotuladas (como diagramas VPC de fornecedores cloud), setas ortogonais com rótulos monoespaçados, em um fundo de papel quadriculado legal. Um arquivo HTML autossuficiente é a fonte da verdade; PNG / TSX / artefato são derivados dele.

Requisitos

• Python 3.9+ (apenas biblioteca padrão para fetch_icons.py, build.py e share.py)
• Acesso de rede às fontes de ícones (svgl.app, raw.githubusercontent.com, cdn.jsdelivr.net, aws.amazon.com e d1.awsstatic.com para ícones AWS, services.google.com para ícones Google Cloud, learn.microsoft.com e arch-center.azureedge.net para ícones Azure, além do site ou repositório da própria marca para name=URL) ao buscar ícones
• Playwright + Chromium para render_png.py: pip install playwright && python3 -m playwright install --with-deps chromium

Fluxo de trabalho

1. Definir o conteúdo (nós, grupos, arestas)
2. Buscar ícones — scripts/fetch_icons.py
3. Planejar coordenadas — ler references/geometry.md
4. Construir o HTML a partir de assets/template.html — scripts/build.py
5. Renderizar um PNG e olhar para ele antes de entregar
6. Entregar no(s) formato(s) solicitado(s)
7. Opcionalmente, compartilhá-lo na galeria pública

Etapa 1 — Conteúdo

A partir da lista de tecnologias/serviços do usuário, decida:

• Nós: cada tecnologia = um nó (nome + uma função curta em letras minúsculas como http server, sqlite db)
• Grupos: desenhe uma caixa ao redor de coisas que compartilham um runtime, fornecedor ou repositório (por exemplo, uma caixa de provedor cloud contendo uma caixa de runtime; uma caixa de monorepo para ferramentas). Aninhamento de um nível de profundidade é suficiente; mais fundo fica poluído. Escreva os rótulos dos grupos na própria caixa da marca (GitHub, npm); o template os mostra como escritos.
• Arestas, três tipos:
  • sólida colorida com acento = o fluxo principal de requisição/dados (um caminho contínuo é o melhor)
  • sólida neutra = conexões internas secundárias
  • tracejada neutra = relações de tempo de desenvolvimento/implantação (CI, hooks git, deploy IaC)

Se o usuário forneceu apenas uma lista plana de ferramentas, infira grupos e fluxos sensatos com base no que as ferramentas são — só pergunte quando uma ferramenta for ambígua o suficiente para que o diagrama fique errado de qualquer forma.

Etapa 2 — Ícones

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"

Formas de especificação: nome (nome usado como slug), nome:slug (slug diferente), nome=URL (URL explícita), nome:aws/<Nome> (ícone oficial AWS), nome:gcp/<Produto> (ícone oficial Google Cloud), nome:azure/<Nome> (ícone oficial Azure). O script tenta, nesta ordem: svgl → devicon → gilbarbara/logos, escreve arquivos mais manifest.json, e sinaliza ícones cujo preenchimento é branco. svgl (svgl.app) é primeiro porque carrega marcas oficiais atuais para marcas modernas de desenvolvimento (TanStack, Better Auth, Hono...). Quando um logotipo tem versões clara/escura, a clara se torna <nome> (os blocos são brancos em ambos os temas) e a escura é salva como <nome>_dark para rótulos de grupo. svgl é correspondido apenas por título exato, então uma falha apenas passa adiante. Sua API também expõe variantes wordmark — ocasionalmente úteis para um rótulo de grupo largo, nunca para blocos.

Regras que importam mais que a mecânica:

• Nunca recolorir um logotipo. Os usuários notam. Se um logotipo for branco ou muito claro para um bloco branco, coloque-o em um bloco escuro (classe tile dark) em vez de tocar em seu preenchimento. A flag white_fill do manifest é uma heurística — um preenchimento branco pode ser um detalhe interno em uma marca colorida (tRPC, Ubuntu), então dê uma olhada no SVG antes de pegar o bloco escuro.
• Apenas marcas oficiais. simple-icons é deliberadamente não uma fonte: seus glifos são redesenhos monocromáticos, e os usuários os identificam como errados imediatamente. Quando todas as fontes falham (FAIL), encontre o arquivo oficial e passe-o como nome=URL — procure no repositório do projeto (raiz logo*.svg, docs/, assets/, public/) e em seu site (/logo.svg, /favicon.svg, /images/logo.svg). Algumas marcas vivem apenas no repositório (a do Lefthook é logo_sign.svg na raiz de evilmartians/lefthook).
• Conceitos abstratos recebem pictogramas, não texto. Um nó como "ambiente de desenvolvimento", "cron", "fila", "cache" ou "receptor de webhook" não tem marca — recorra a um ícone de linha Lucide via nome:lucide/<ícone> (por exemplo, devenv:lucide/terminal, cron:lucide/clock; navegue em lucide.dev/icons). Sem texto em um bloco, sem emoji.
• Subprodutos de fornecedor (Cloudflare D1/R2/KV...) geralmente não têm logotipo distinto: apenas reutilize o logotipo do fornecedor no bloco e deixe o nome do nó carregar a distinção ("Cloudflare D1" / "sqlite db").
• AWS usa ícones próprios da AWS. Cada serviço tem um: busque-o com nome:aws/<Nome>, lido do pacote oficial de ícones da AWS em tempo de execução (por exemplo, lambda:aws/lambda, aws:aws/AWS-Cloud-logo, s3:aws/s3). O prefixo AWS- / Amazon- é opcional, acrônimos comuns funcionam (s3, sqs, sns, ses, ecs, eks, ecr, elb, alb, nlb, iam, kms, msk, vpc), e uma falha imprime cada nome. Os slugs aws, amazonwebservices e aws-* vão para o mesmo pacote, e o que ele não carrega resulta em FAIL em vez de cair em uma cópia de terceiros. Sempre escreva o prefixo aws/ para um serviço: um dynamodb simples ainda passa pela cadeia de terceiros. Mantenha o pacote e arquivos de ícones soltos fora dos repositórios: a AWS permite os ícones em diagramas, e a redistribuição não é confirmada.
• A área AWS segue as próprias regras de desenho da AWS. Ícones de serviço carregam seu próprio quadrado e funcionam em fundos claro e escuro, então use tile bare: um bloco branco apenas dobra a moldura. Pessoas e nós genéricos dentro dela usam ícones gerais da AWS (user:aws/General-User; também General-Users, General-Client, General-Internet, General-Server) em tile bare res com o par lt/dk do template. Grupos usam o group aws do template para AWS Cloud (com aws:aws/AWS-Cloud-logo no rótulo), mais region, az, vpc, private ou public para o resto: cantos quadrados, apenas contorno, rótulo em tinta, sem tonalidade do fornecedor, e um ícone de 30px alinhado no canto em vez do de 14px. Dentro de uma VPC, mostre sub-redes públicas e privadas quando você souber ou puder inferir com segurança a divisão (um balanceador de carga voltado para a internet em público; servidores de aplicação e bancos de dados em privado): uma VPC plana é a primeira coisa que pessoas da AWS notam. Arestas dentro dela usam uma cor e uma ponta de seta aberta: <path class="aws" ... marker-end="url(#open)"/>, aws dash para desenvolvimento/implantação, rótulos .el simples, e nenhuma legenda para elas. Nomeie nós Amazon S3 / AWS Fargate, não um S3 / Fargate simples; uma forma curta como ALB vai na linha de função, abaixo do nome completo (Elastic Load Balancing). Nomes podem ocupar duas linhas, mas Amazon / AWS devem permanecer na linha da primeira palavra: se quebrar logo após o prefixo, alargue esse nó (left:<centerX-76>px; width:152px).
• Google Cloud usa ícones próprios do Google. Busque-os com nome:gcp/<Produto>, lidos dos pacotes oficiais do Google em tempo de execução (por exemplo, run:gcp/cloud-run, lb:gcp/load-balancing, memorystore:gcp/memorystore). Apenas produtos principais têm seu próprio ícone (Cloud Run, Cloud SQL, Cloud Storage, BigQuery, GKE, Compute Engine, Vertex AI...). Cada outro produto usa o ícone de sua categoria, conforme especifica o guia do Google: Cloud Load Balancing e Cloud CDN recebem ambos Networking, Memorystore e Firestore recebem ambos Databases. Escreva o nome do produto e o script escolhe o ícone. O prefixo Cloud / Google é opcional, algumas formas curtas funcionam (vpc, iam, kms, iap, gce, gcs), e uma falha imprime cada nome. gcp/storage é a categoria Storage; Cloud Storage é gcp/cloud-storage. Os slugs gcp-* e google-cloud-* vão para os mesmos pacotes, e o que eles não carregam resulta em FAIL em vez de cair em uma cópia de terceiros: essas cópias são os ícones hexagonais aposentados, que o Google diz para não usar. Sempre escreva o prefixo gcp/ para um produto: um bigquery simples ainda passa pela cadeia de terceiros. gcp:google-cloud é a marca Google Cloud para o rótulo do grupo. Gemini e Firebase não estão nos pacotes: use o gemini e firebase simples. Mantenha os pacotes e arquivos de ícones soltos fora dos repositórios: o Google oferece os ícones para diagramas e documentação, e a redistribuição não é confirmada.
• Diagramas Google Cloud mantêm o estilo normal, com grupos do Google. Os próprios diagramas do Google (painel azul sólido, cartões horizontais) são deliberadamente não copiados: os ícones vão no bloco branco normal, e as arestas e a legenda permanecem como de costume. Grupos usam o group gcp do template para Google Cloud (com gcp:google-cloud no rótulo), mais vpc, region, subnet ou zone. Uma VPC é global e uma sub-rede é regional, então coloque a região dentro da VPC, nunca a VPC dentro de uma região. Serviços globais e serverless (um balanceador de carga externo, Cloud Storage, Cloud Run) ficam fora da VPC. Como os ícones são compartilhados, sempre escreva o nome completo do produto (Cloud Load Balancing, não LB), e alargue um nó cujo nome quebraria (left:<centerX-76>px; width:152px).
• Azure usa ícones próprios da Microsoft. Cada serviço tem um: busque-o com nome:azure/<Nome>, lido do pacote oficial da Microsoft em tempo de execução (por exemplo, app:azure/app-service, azure:azure/Azure-A, vault:azure/key-vault). O prefixo Azure- / Microsoft- e um plural s são opcionais, formas curtas comuns funcionam (aks, vm, vnet, nsg, waf, blob, cosmos, redis, postgres, functions, front-door, apim, ai-search), e uma falha imprime cada nome. Os slugs azure, microsoft-azure e azure-* vão para o mesmo pacote, e o que ele não carrega resulta em FAIL em vez de cair em uma cópia de terceiros. Sempre escreva o prefixo azure/ para um serviço: um cosmos simples ainda passa pela cadeia de terceiros. O Microsoft Entra ID tem um conjunto de ícones separado: passe seu arquivo oficial como nome=URL. A Microsoft permite esses ícones apenas em diagramas de arquitetura, materiais de treinamento e documentação. Nunca corte, vire, gire ou reformate um, use-o apenas para o serviço Microsoft que ele representa, e mantenha o pacote e arquivos de ícones soltos fora dos repositórios.
• Diagramas Azure mantêm o estilo normal, com as cores de grupo da Microsoft. Os próprios diagramas da Microsoft são deliberadamente não copiados: os ícones vão no bloco branco normal, e as arestas e a legenda permanecem como de costume. Grupos usam o group azure do template para Azure (com azure:azure/Azure-A no rótulo), mais rg, region, vnet, subnet ou zone, e um rótulo vnet ou subnet carrega seu ícone (vnet:azure/vnet, subnet:azure/subnet). Uma VNet pertence a uma região, então ela vai dentro da região. Serviços globais como Front Door ficam fora da região. O App Service fica fora da VNet a menos que seja executado em um App Service Environment, e um serviço PaaS alcançado através de um endpoint privado pode ficar dentro dela com private endpoint como sua função. A Microsoft pede o nome completo do serviço ao lado de cada ícone (Azure SQL Database, não SQL), então alargue um nó cujo nome quebraria (left:<centerX-76>px; width:152px).
• As regras de um fornecedor cobrem apenas sua própria área. As regras AWS, Google Cloud e Azure se aplicam apenas dentro do grupo desse fornecedor, mesmo quando o diagrama não mostra mais nada. Tudo fora dele, como um usuário ao lado ou uma aresta que o cruza, mantém os blocos, grupos, arestas e legenda normais.
• Nós não-marca (usuário, navegador, internet, dispositivos, servidor bare-metal): copie um glifo de assets/generic/ para o diretório de ícones sob o nome do nó, ou use nome:lucide/<ícone> — não use emoji. Estes não são logotipos de marca, então tingi-los com a cor da tinta do diagrama é aceitável (o script de busca faz isso para Lucide automaticamente).
• Ícones de rótulo de grupo renderizam a 14px — eles precisam de uma marca de glifo quadrada. Marcas nominativas e logotipos largos se transformam em lama nesse tamanho; se o ícone principal for uma marca nominativa, busque o ícone quadrado da marca separadamente para o rótulo (svgl geralmente o tem; caso contrário, o próprio ícone do projeto ou arquivo favicon).
• Rótulos de grupo ficam sobre a tonalidade do grupo, não sobre um bloco branco, então no tema escuro uma marca com partes pretas desaparece ali. Se fetch_icons.py salvou <nome>_dark, use o par lt/dk do template no rótulo; se não houver variante escura e a marca tiver partes pretas, adicione a classe plate ao <img> do rótulo (fundo branco, apenas no tema escuro).
• Logotipos raster (png/webp) são aceitáveis; o buffer do Chromium os trata bem o suficiente, então não gaste tempo convertendo para SVG a menos que a saída pareça ruim.

Etapa 3 — Coordenadas

Leia references/geometry.md. As regras principais:

• 100px = 1 unidade
• Os nós mais à esquerda começam em X=80; os mais à direita terminam em X=1580 (largura do layout de 1500px, centralizado em um canvas de 1680px). Grupos podem se estender até X=80..1580, com 20px extras de preenchimento de cada lado.
• Nós = 68×68px, seus ícones preenchem todo o bloco. Nós amplos (nome de duas linhas ou um role mais longo) usam width:152px; seu ícone fica centralizado na parte de cima.
• Espaçamento vertical entre nós = 120px, entre grupos = 80px.
• Um grupo para um único serviço com espaço de sobra deve ser ligeiramente maior que seu nó (112×112), para que não pareça uma caixa apertada.
• Arestas são desenhadas como caminhos retangulares em grade. Os cantos são arredondados para um rx de 8px; três segmentos no máximo, e nunca atravessam outro nó.

Etapa 4 — Construir

python3 scripts/build.py <icons-dir> <output.html>

O HTML resultante é autossuficiente: ícones embutidos como data URIs, todas as definições de grupo/tema inline, pronto para ser visualizado em qualquer navegador moderno.

Etapa 5 — Renderizar

python3 scripts/render_png.py <output.html> <out.png> --width 1680
python3 scripts/render_png.py <output.html> <out-dark.png> --width 1680 --dark

Antes de entregar, olhe para o PNG. Verifique se:

• Os ícones estão na posição correta, com blocos brancos e sem estouro
• As arestas estão em zigue-zague correto, sem cruzar nós
• O tema escuro parece bom (não apenas uma inversão)
• Os ícones AWS/GCP/Azure estão usando as variantes escuras, se aplicável
• Se algo parece estranho, ajuste as coordenadas e reconstrua

Etapa 6 — Entregar

Os formatos possíveis: HTML, PNG, PNG escuro, SVG, TSX. Sempre entregue o HTML primeiro e, em seguida, derive os outros formatos dele. Para SVG, use a saída do Playwright para re-exportar; nunca redesenhe do zero.

Etapa 7 — Compartilhar (Opcional)

Se o usuário consentir explicitamente em compartilhar o diagrama na galeria pública:

python3 scripts/share.py <output.html> [tags...]

Isso envia para o registro público stack-diagram.gallery. Nenhum consentimento, nenhum compartilhamento — esta etapa nunca é automática.

Referências

• references/geometry.md — sistema de coordenadas e layout
• assets/template.html — modelo HTML base
• assets/generic/ — glifos não-marca (usuário, navegador, etc.)
• UPSTREAM.md — mudanças em relação ao caru-ini/stack-diagram

Considerações finais

Esta skill é projetada para produzir diagramas de arquitetatura que parecem profissionais, consistentes e tecnicamente precisos. Siga as regras de ícones rigorosamente — os usuários notam logotipos errados ou reposicionados. Use o Playwright para renderizar e sempre inspecione a saída antes de entregar. Quando em dúvida, pergunte ao usuário — um diagrama correto é melhor que um rápido.