Diagramas de arquitetura no estilo AWS
Visão Geral
Produza diagramas que seguem as convenções do diagrama de arquitetura de referência da AWS: nomes de serviço precisos, limites de conta/Região/VPC rotulados, rótulos de fluxo curtos e uma tela sem desordem. "Estilo AWS" descreve essas convenções; não exige por si só ícones oficiais da AWS ou Graphviz.
Mermaid e Graphviz DOT são formatos de autoria pares. Mermaid geralmente se adapta a documentação inline, sensível a temas e revisável por texto; DOT geralmente se adapta a ativos de ícones AWS locais exatos, composição controlada e SVG/PNG prontos para apresentação. Use um quando satisfizer todo o contrato de entrega e ambos quando públicos ou artefatos distintos justificarem a manutenção adicional.
Quando Usar
Use esta skill para diagramas de arquitetura, topologia, contexto de sistema ou fluxo de dados AWS com base em evidências. Não use para um visual que não seja AWS ou quando uma tabela sozinha comunicar os fatos solicitados de forma mais clara.
Racionalizações Comuns
- "Estilo AWS significa DOT" ignora renderizadores Mermaid que atendem ao contrato real.
- "Ambos os formatos são mais seguros" cria custo de sincronização sem dois consumidores nomeados.
- "O serviço provavelmente se conecta aqui" não é evidência para uma aresta.
Bandeiras Vermelhas
Pare e resolva recursos ou relacionamentos não suportados, um renderizador de destino ambíguo, direitos ou ativos de ícones ausentes, evidências de origem conflitantes ou uma Região solicitada fora do escopo autorizado antes de desenhar ou consultar a infraestrutura ativa.
A regra que supera a estética
Desenhe apenas o que a fonte estabelece. Cada nó, aresta, limite, Região e protocolo deve rastrear algo real — Terraform, CloudFormation, CDK, configuração implantada ou uma declaração por escrito do proprietário. Um diagrama é um artefato de evidência que por acaso é visual.
Nunca adicione um serviço, conexão, Zona de Disponibilidade, VPC ou Região porque a imagem parece desequilibrada sem ele. Se a fonte não estabelecer um limite, deixe-o de fora; um diagrama esparso honesto vence um decorativo completo. Quando algo está implantado, mas desabilitado, diga isso no nó (WEB_PUSH_ENABLED=false, "Implantado, desabilitado em lançamento") em vez de desenhá-lo como se estivesse ativo, e marque o que outra equipe possui para que um leitor não pense que você o controla.
Declare a proveniência no próprio diagrama — uma legenda nomeando a fonte, como "rastreado de <iac-dir>/*.tf em <revisão>" ou "inventário somente leitura ativo, <data>" — e repita-a em um comentário de cabeçalho na fonte DOT.
Nomeie o recurso, não apenas o serviço
Um ícone de serviço sozinho não identifica nada. Um glifo DynamoDB magenta rotulado como "Operações" poderia ser uma tabela, um stream ou um índice, e um leitor não tem como encontrá-lo no console. Cada nó declara três fatos:
- Como é chamado na AWS. O nome real implantado —
acme-orders-events, não um alias amigável como "Pedidos". Escreva um ID de conta como<conta>em vez dos dígitos; nunca coloque um segredo, token ou endpoint em um diagrama. - Que tipo de recurso é. Escrito, em cinza, sob o nome: "Tabela DynamoDB", "Bucket S3", "Função Lambda", "API HTTP do API Gateway", "WAFv2 web ACL", "Identidade de e-mail SES v2".
- Para que serve. Uma linha, e apenas onde um leitor não puder inferi-lo.
Para saída Graphviz, use um ícone de recurso onde a AWS publica um — Res_Amazon-DynamoDB_Table, Res_Amazon-Simple-Storage-Service_Bucket, Res_AWS-Lambda_Lambda-Function — e um ícone de serviço (Arch_) para todo o resto. O ícone reforça a identidade; nunca deve ser a única coisa que a carrega, porque um ícone não é legível em escala de cinza, em tamanho de miniatura ou por um leitor de tela.
Escolha o formato a partir dos requisitos
Não há vencedor global e nenhum formato padrão. Honre um formato de origem explicitamente solicitado, a menos que entre em conflito com outro critério de aceitação. Caso contrário, compare as necessidades reais de entrega:
| Requisito | Mermaid tende a se adequar melhor | Graphviz DOT tende a se adequar melhor |
|---|---|---|
| Revisão em repositório | Renderização Markdown inline, diffs textuais compactos | Fonte textual revisável mais artefatos renderizados separadamente |
| Tipo de diagrama | Sequência, fluxo, estado, dependência e visualizações de arquitetura diretas | Topologia densa, limites aninhados e gráficos que precisam de roteamento de aresta deliberado |
| Visuais AWS | Nomes, limites, cores ou pacotes de ícones fornecidos pelo renderizador no estilo AWS | Ativos de ícone AWS exatos publicados localmente no repositório |
| Layout | Layout responsivo gerenciado pelo renderizador e adaptação de tema | Ranques, portas, clusters, espaçamento e composição fixa precisos |
| Entrega | Documentação que deve renderizar onde é escrita | SVG/PNG controlados para apresentações, documentos e superfícies de apresentação |
| Ferramentas | O renderizador de destino já suporta a sintaxe e versão Mermaid exigidas | Graphviz e os ativos locais exigidos estão disponíveis no ambiente de construção ou autoria |
Se o conteúdo solicitado for na verdade tabular, use uma tabela Markdown em vez de transformá-lo em uma imagem. Para uma troca ordenada de participantes, sequenceDiagram do Mermaid geralmente é o ajuste natural; esta é uma vantagem de tipo de diagrama, não uma preferência geral pelo Mermaid.
Mermaid suporta diagramas de arquitetura e pacotes de ícones configuráveis, mas não se pode assumir que um renderizador hospedado fornecerá ativos AWS locais do repositório, registro de pacote personalizado ou a mesma versão do Mermaid que um renderizador local controlado. O Graphviz pode carregar ativos de imagem locais diretamente, portanto é a escolha confiável quando ativos de ícone exatos e composição exportada fixa são critérios de aceitação, não apenas porque a solicitação diz "estilo AWS".
Conte os trade-offs de ambos os lados. Mermaid pode variar entre versões de renderizador, pacotes de ícones disponíveis e temas de host. DOT adiciona uma etapa de renderização e artefatos gerados que devem permanecer sincronizados com a fonte editável. Selecione o formato cujos custos correspondem ao repositório e destino, em vez de tratar os pontos fortes de qualquer ferramenta como universais.
Se o suporte do renderizador, a fidelidade do ícone, a composição fixa ou os arquivos de saída esperados alterassem materialmente o resultado e a solicitação for ambígua, esclareça o contrato de entrega. Caso contrário, selecione o formato que satisfaz os requisitos conhecidos com o mínimo de mecanismos específicos do projeto.
Quando o Mermaid for selecionado, mantenha as regras de evidência, proveniência, nomenclatura de recursos e acessibilidade acima, valide a fonte em seu renderizador de destino e pare antes do fluxo de trabalho específico do Graphviz abaixo.
Quando ambos os formatos são justificados
Produza Mermaid e DOT quando eles satisfazem requisitos reais diferentes, como revisão inline de repositório mais saída de apresentação com ícones AWS exatos. A entrega dupla não é automaticamente melhor: é justificada apenas quando ambos os artefatos têm um consumidor nomeado ou critério de aceitação.
Nenhuma fonte é canônica por padrão. Derive ambas do mesmo inventário verificado de recursos e relacionamentos, carregue a mesma proveniência e verifique se nós, arestas, limites, Regiões, propriedade e incerteza concordam. Um formato pode adicionar estrutura específica de apresentação sem alterar a arquitetura que afirma. Nomeie um formato como autoritativo apenas quando o usuário ou a política do repositório atribuir explicitamente essa função.
Para um mapa de sistema completo excepcionalmente denso que precisa de ícones AWS exatos, composição fixa ou posicionamento de conector em nível de porta, DOT mais seu SVG e PNG podem servir como o artefato de apresentação e ícone AWS. Uma renderização Mermaid pode servir como o companheiro mantido e revisável inline quando isso também for exigido. Para um fluxo focado sem esses requisitos específicos de DOT, apenas Mermaid pode satisfazer o contrato. Estas são escolhas orientadas por requisitos, não uma razão para produzir ambos os formatos para cada diagrama.
Fluxo de trabalho Mermaid
1. Selecione o tipo de diagrama Mermaid
Use architecture-beta ou um fluxograma para arquitetura e topologia, um sequenceDiagram para trocas ordenadas e um diagrama de estado apenas para transições de estado reais. Confirme se o renderizador de destino suporta a sintaxe selecionada e qualquer pacote de ícones; não assuma que GitHub, um site de documentação e um CLI Mermaid local executam a mesma versão ou configuração. Ao usar símbolos Iconify, mantenha o nome e tipo completos do recurso AWS em texto; um ícone nunca deve ser o único identificador de recurso.
2. Codifique o inventário verificado
Represente limites de conta, Região, VPC, Zona de Disponibilidade, sub-rede e propriedade da AWS apenas quando a evidência os estabelecer. Use nomes e tipos de recurso completos, arestas curtas rotuladas e anotações visíveis para relacionamentos permitidos ou inferidos. Mantenha a proveniência no Markdown próximo e, quando a sintaxe permitir, em um comentário de código.
3. Renderize e inspecione no ambiente de destino
Use o comando Mermaid fixado do repositório ou a build de documentação. Valide o bloco de código exato ou a fonte .mmd que será enviada e, em seguida, inspecione o resultado renderizado em sua largura e tema pretendidos. Verifique rótulos cortados, arestas sobrepostas, ícones ou sintaxe não suportados, contraste inacessível e deriva semântica do inventário verificado. Corrija a fonte editável e re-renderize até que fique legível.
Registre pacotes de ícones não incorporados explicitamente. Para Mermaid CLI, uma renderização reproduzível de símbolo AWS pode usar:
mmdc --iconPacks '@iconify-json/logos' \
-i system-context-aws.mmd -o system-context-aws.svg -b white
Trate um fallback ? como uma renderização falha, não uma degradação cosmética. O suporte a pacotes de ícones pode variar por versão do Mermaid e renderizador de layout; verifique a saída real visual e estruturalmente. Se um renderizador suportado perder ícones registrados, use outro renderizador suportado que os preserve e documente o trade-off de layout. Não reivindique portabilidade inline a menos que o host de destino também registre o pacote exigido.
4. Entregue os artefatos exigidos
Mantenha Mermaid inline quando esse for o contrato do repositório. Quando saídas SVG ou PNG independentes forem exigidas, renderize-as deterministicamente com a versão Mermaid fixada do repositório e documente o comando de reprodução.
Fluxo de trabalho Graphviz
1. Estabeleça a arquitetura a partir da fonte
Leia o IaC e faça o inventário do que realmente existe antes de desenhar qualquer coisa. Encontre o diretório onde este projeto o mantém — infra/, terraform/, deploy/, um aplicativo CDK — em vez de assumir um layout:
iac_dir=infra # seja qual for o que este repositório realmente usa
grep -hoE '^resource "aws_[a-z0-9_]+"' "$iac_dir"/*.tf | sort | uniq -c | sort -rn
Em seguida, extraia os detalhes que tornam as arestas reais e os nomes que vão nos nós: nomes de função, nomes de tabela, nomes de bucket, regras de eventos e suas programações, notificações S3, autorizadores e qualquer concessão entre contas ou entre stacks. Resolva nomes através de suas variáveis e locais para o valor realmente implantado. Observe a Região da variável que a define, não de suposição.
1b. Quando não há IaC, ou o IaC é apenas parte do legado
Às vezes, a coisa a ser diagramada é uma conta ativa para a qual ninguém tem Terraform, ou o Terraform cobre apenas uma fração do que está implantado. Então, a fonte é a conta ativa, somente leitura, e o diagrama deve ser explícito de que é isso que é.
Comece de um predicado de tag em vez de uma varredura serviço por serviço, porque é a única maneira de limitar "o que pertence a este sistema":
aws resourcegroupstaggingapi get-resources --region <regiao> \
--tag-filters 'Key=<chave>,Values=<v1>,<v2>'
Várias chaves de tag precisam de uma solicitação cada, unidas por ARN posteriormente — passar duas chaves em uma solicitação aplica E, descartando silenciosamente tudo que carrega apenas uma delas. Registre a contagem e data resultantes; é um instantâneo, não um fato.
A API de tagging não retorna todos os tipos de recurso, e tags não são propriedade. Portanto, a consulta de tag fornece o conjunto de nós, e relacionamentos vêm das APIs que realmente os modelam:
| Para estabelecer | Leia |
|---|---|
| Cabeamento de entrada | elbv2 describe-load-balancers, describe-target-groups |
| Quais caminhos são permitidos | ec2 describe-security-groups, describe-vpcs |
| O que uma camada de computação pode chamar | iam get-instance-profile, depois get-policy-version |
| Forma e réplicas da camada de dados | rds describe-db-instances, elasticache describe-* |
| Cabeamento assíncrono | políticas de redirecionamento de fila, notificações S3, regras de eventos |
Resolva cada CIDR que encontrar para uma VPC nomeada antes de desenhá-la; um 10.16.0.0/16 não resolvido em um diagrama não diz nada a um leitor.
1c. Diga em que tipo de evidência cada aresta se baseia
Isso é mais importante ao ler uma conta ativa, onde é tentador desenhar uma linha porque dois recursos compartilham um prefixo de nome. Separe as classes visualmente e defina-as no diagrama e em sua prosa:
- Cabeamento que a própria AWS relata — os alvos de um grupo de destino, a fonte de uma réplica. A classe mais forte; a AWS está modelando o relacionamento para você.
- Um caminho que algo permite — uma regra de grupo de segurança, uma política de bucket. Isso estabelece que uma chamada pode ocorrer, não que ocorre. Observe quando uma regra é escopo CIDR em vez de escopo grupo de segurança: ela autoriza um intervalo inteiro, não a única carga de trabalho da qual você desenhou a seta.
- Uma concessão que uma identidade detém — uma declaração de política IAM. Mesma cautela, mais a concessão não é a permissão efetiva até que SCPs, limites de permissão e políticas de recurso sejam avaliadas.
- Inferência de nomes ou tags — desenhe tracejado, rotule com a incerteza ou deixe de fora. Nunca sólido.
Ausência é um achado que vale a pena desenhar também. Quando uma função que "obviamente" fala com uma fila acaba por não ter nenhuma ação sqs:*, um nó dizendo isso é mais útil do que uma seta ausente, porque descarta a suposição errada em vez de deixá-la em aberto.
[... truncado]