stack-diagram

O que stack-diagram faz?

Produz diagramas de arquitetura no estilo de desenhos de engenharia: logotipos reais em tiles brancos, caixas de grupo rotuladas (como diagramas VPC de cloud vendors), setas ortogonais com rótulos monoespaçados, em um fundo legal de papel quadriculado. Um único 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 próprio site ou repositório da 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 observá-lo antes de entregar
6. Entregar no(s) formato(s) solicitado(s)
7. Opcionalmente, compartilhá-lo na galeria pública

Passo 1 — Conteúdo

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

• Nós: cada tecnologia = um nó (nome + um papel curto em minúsculas como servidor http, banco sqlite)
• Grupos: desenhe uma caixa ao redor de coisas que compartilham um runtime, vendor ou repositório (ex.: uma caixa de provedor de nuvem contendo uma caixa de runtime; uma caixa de monorepo para ferramentas). Aninhar um nível de profundidade é aceitável; mais fundo fica confuso. Escreva os rótulos dos grupos na caixa da própria marca (GitHub, npm); o modelo os mostra como escritos.
• Arestas, três tipos:
  • sólida com cor de destaque = 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 desenvolvimento/implantação (CI, hooks git, IaC deploy)

Se o usuário deu apenas uma lista plana de ferramentas, infira grupos e fluxos sensatos a partir do que as ferramentas são — pergunte apenas quando uma ferramenta for ambígua a ponto de o diagrama ficar errado de qualquer forma.

Passo 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"
python3 scripts/fetch_icons.py <icons-dir> "k8s:kubernetes" "ing:k8s/ingress" "svc:k8s/service" "deploy:k8s/deployment" "pod:k8s/pod"

Formas de especificação: name (nome usado como slug), name:slug (slug diferente), name=URL (URL explícita), name:aws/<Nome> (ícone oficial AWS), name:gcp/<Produto> (ícone oficial Google Cloud), name:azure/<Nome> (ícone oficial Azure), name:k8s/<Recurso> (ícone oficial Kubernetes). O script tenta, em ordem: svgl → devicon → gilbarbara/logos, escreve arquivos mais manifest.json, e sinaliza ícones cujo preenchimento é branco. svgl (svgl.app) é o primeiro porque carrega marcas oficiais atuais para marcas de desenvolvimento modernas (TanStack, Better Auth, Hono...). Quando um logotipo tem versões clara/escura, a clara se torna <name> (tiles são brancos em ambos os temas) e a escura é salva como <name>_dark para rótulos de grupo. svgl é correspondido apenas pelo 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 tiles.

Regras que importam mais do que a mecânica:

• Nunca recolorir um logotipo. Os usuários notam. Se um logotipo for branco ou muito claro para um tile branco, coloque-o em um tile escuro (classe tile dark) em vez de tocar no seu preenchimento. A flag white_fill do manifesto é 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 usar o tile escuro.
• Apenas marcas oficiais. simple-icons é deliberadamente não uma fonte: seus glifos são redesenho monocromáticos, e os usuários os chamam de errados à vista. Quando toda fonte falhar (FAIL), encontre o arquivo oficial e passe-o como name=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 da 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 name:lucide/<icone> (ex.: devenv:lucide/terminal, cron:lucide/clock; navegue em lucide.dev/icons). Sem texto em um tile, sem emoji.
• Subprodutos de vendors (Cloudflare D1/R2/KV...) geralmente não têm logotipo distinto: apenas reutilize o logotipo do vendor no tile e deixe o nome do nó carregar a distinção ("Cloudflare D1" / "banco sqlite").
• AWS usa ícones próprios da AWS. Cada serviço tem um: busque-o com name:aws/<Nome>, lido do pacote oficial de ícones da AWS em tempo de execução (ex.: 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 FAIL em vez de cair para 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 de 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 claros e escuros, então use tile bare: um tile 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 modelo. Grupos usam o group aws do modelo para AWS Cloud (com aws:aws/AWS-Cloud-logo no rótulo), mais region, az, vpc, private ou public para o restante: cantos quadrados, apenas contorno, rótulo em tinta, sem tonalidade de vendor, e um ícone de 30px rente ao canto em vez 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 as 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 papel, sob o 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 name:gcp/<Produto>, lido dos pacotes oficiais do Google em tempo de execução (ex.: 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 o guia do Google especifica: Cloud Load Balancing e Cloud CDN ambos recebem Networking; Memorystore e Firestore ambos recebem 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 FAIL em vez de cair para 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 os gemini e firebase simples. Mantenha os pacotes e arquivos de ícones soltos fora de 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: ícones vão no tile branco normal, e arestas e legenda permanecem como de costume. Grupos usam o group gcp do modelo 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 name:azure/<Nome>, lido do pacote oficial da Microsoft em tempo de execução (ex.: app:azure/app-service, azure:azure/Azure-A, vault:azure/key-vault). O prefixo Azure- / Microsoft- e um s plural 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 FAIL em vez de cair para uma cópia de terceiros. Sempre escreva o prefixo azure/ para um serviço: um cosmos simples ainda passa pela cadeia de terceiros. Microsoft Entra ID tem um conjunto de ícones separado: passe seu arquivo oficial como name=URL. A Microsoft permite esses ícones apenas em diagramas de arquitetura, materiais de treinamento e documentação. Nunca corte, vire, gire ou remodele um, use-o apenas para o serviço Microsoft que ele representa, e mantenha o pacote e arquivos de ícones soltos fora de repositórios.
• Diagramas Azure mantêm o estilo normal, com cores de grupo da Microsoft. Os próprios diagramas da Microsoft são deliberadamente não copiados: ícones vão no tile branco normal, e arestas e legenda permanecem como de costume. Grupos usam o group azure do modelo 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. App Service fica fora da VNet a menos que execute em um App Service Environment, e um serviço PaaS acessado por meio de um ponto de extremidade privado pode ficar dentro dela com ponto de extremidade privado como seu papel. 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).
• Kubernetes usa ícones oficiais da comunidade. Busque-os com name:k8s/<Recurso>, lido do conjunto de ícones oficial kubernetes/community (ex.: pod:k8s/pod, deploy:k8s/deployment, svc:k8s/service, ing:k8s/ingress, cm:k8s/configmap, secret:k8s/secret, node:k8s/node, api:k8s/kube-apiserver). Ícones usam as variantes não rotuladas para recursos e infraestrutura para manter glifos limpos e sem desordem na escala do diagrama, e variantes rotuladas para componentes do plano de controle. Nomes curtos comuns e plurais funcionam (svc/service/services, deploy/deployment/deployments, po/pod/pods, cm/configmap/configmaps, sts/statefulset, ds/daemonset, node/nodes, etc.). Uma falha imprime nomes disponíveis. Os slugs k8s, kubernetes e k8s/k8s fornecem o logotipo oficial da roda do Kubernetes através da cadeia.
• Diagramas Kubernetes mantêm o estilo normal por padrão. Ícones ficam no tile branco normal, o que os unifica com outras tecnologias na stack (como NGINX, cert-manager, bancos de dados externos ou balanceadores de carga de nuvem) e fornece elevação e contraste consistentes em fundos de papel quadriculado. Para glifos mínimos independentes, tile bare também é suportado. Grupos usam grupos padrão (cluster, namespace, node, pod). Credit o Conjunto de Ícones Kubernetes no rodapé do diagrama.
• As regras de um vendor cobrem apenas sua própria área. As regras AWS, Google Cloud, Azure e Kubernetes aplicam-se apenas dentro do grupo desse vendor, 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 tiles, grupos, arestas e legenda normais.
• Nós não relacionados a marcas (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 name:lucide/<icone> — não use emoji. Esses não são logotipos de marcas, então tingi-los com a cor de 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. Wordmarks e lockups largos viram lama nesse tamanho; se o ícone principal for um wordmark, busque o ícone quadrado da marca separadamente para o rótulo (svgl geralmente tem; caso contrário, o próprio ícone do projeto ou arquivo favicon).
• Rótulos de grupo ficam na tonalidade do grupo, não em um tile branco, então no tema escuro uma marca com partes pretas desaparece lá. Se fetch_icons.py salvou <name>_dark, use o par lt/dk do modelo no rótulo; se não houver variante escura e a marca tiver partes pretas, adicione a classe plate ao rótulo...