Como fazer um diagrama de arquitetura de software: guia passo a passo

Quando você senta para fazer seu primeiro diagrama de arquitetura, a parte difícil não é desenhar caixas, e sim decidir o que deixar de fora. Este guia trata de diagramas de arquitetura de software e de sistemas: serviços, bancos de dados, filas, zonas de rede e as conexões entre eles. Seja o seu primeiro diagrama de arquitetura de software ou o décimo do seu time, os passos abaixo ajudam a criar um diagrama que as pessoas conseguem ler e que continua atualizado.

Comece pelo leitor e pela pergunta

Um bom diagrama responde a uma única pergunta. "Tudo no nosso sistema" não é uma pergunta: é um inventário, e inventário fica melhor em uma tabela.

Antes de desenhar qualquer coisa, escreva duas frases:

• Quem vai ler? Uma dev que acabou de entrar, o SRE de plantão, uma revisão de segurança, um product manager, um auditor externo.
• Qual pergunta ele responde? "Por quais serviços passa uma requisição de pedido?", "O que está exposto à internet?", "Para onde vai o tráfego se uma região cair?"

Essas duas frases definem o escopo. Quem acabou de chegar precisa de um nível de detalhe diferente do time de redes. Se você tentar atender os dois com uma imagem só, não atende nenhum.

Escolha o tipo de diagrama

Com a pergunta clara, o tipo praticamente se escolhe sozinho. O modelo C4 é um bom ponto de partida: ele divide um sistema em níveis de zoom chamados context, container, component e code (detalhes em c4model.com).

Na dúvida, comece com um diagrama de contexto. Ele deixa explícitos o limite do sistema e as dependências externas e serve de moldura para todos os diagramas seguintes.

Como fazer um diagrama de arquitetura, passo a passo

1. Defina o escopo e o limite

Escreva o que está dentro do diagrama e o que fica de fora. Os componentes que são do seu time ficam dentro do limite; um provedor de pagamento, um provedor de identidade ou o serviço de outro time ficam fora. Mostre cada sistema externo como uma única caixa: o interior dele não é você quem desenha.

2. Liste os componentes

Faça uma lista antes de desenhar: serviços, bancos de dados, filas, caches, APIs externas, tipos de usuário. Use os nomes que o time realmente usa; se baterem com o nome do repo ou do deployment, melhor ainda. Se a lista for longa demais para ser entendida de relance, provavelmente você tem material para dois diagramas.

3. Desenhe as relações com setas direcionadas e rotuladas

Uma linha sem rótulo só diz que duas coisas estão "relacionadas de algum jeito". Dê a cada seta uma direção e pelo menos duas informações: protocolo e intenção. Inclua sync ou async quando fizer diferença.

checkout-web  --[HTTPS/JSON · POST /orders · sync]-->  order-api
order-api     --[AMQP · order.created · async]------>  orders-queue
order-api     --[TCP 5432 · SQL · read/write]------->  orders-db

A seta vai de quem chama para quem recebe. Não desenhe uma segunda seta para a resposta: isso dobra o número de linhas sem ganho nenhum. Se a ordem de requisições e respostas importa, é para isso que existe o diagrama de sequência.

4. Agrupe com frames

Os grupos são a segunda camada de leitura. Coloque os componentes dentro de limites que significam algo:

• Zonas de rede: subnet pública, subnet privada, DMZ, rede on-premise
• Namespaces do Kubernetes: payments, platform, observability
• Regiões e contas: eu-central-1, us-east-1, contas de prod e staging
• Limites de confiança: onde o tráfego vindo da internet é autenticado

Dá para aninhar (região > VPC > subnet), mas cada nível a mais deixa o diagrama mais difícil de ler.

5. Adicione uma legenda

Se uma cor, um tipo de linha ou um ícone tem significado, a legenda precisa dizer. Linha tracejada é mensagem async? Moldura vermelha é escopo PCI? O que é óbvio para quem desenhou não é óbvio para quem lê seis meses depois.

6. Adicione título, data e responsável

Coloque três informações em um canto de cada diagrama: um título que diga o que ele mostra ("Checkout — visão de containers, prod"), a data da última atualização e o time responsável. Ninguém sabe se um diagrama sem data está atualizado, e ninguém atualiza um diagrama sem dono.

7. Revise com alguém que não desenhou

Mostre o diagrama para alguém que não o desenhou e faça a pergunta que você escreveu no começo. Se a pessoa encontra a resposta sem você explicar, o diagrama funciona. Se você vive dizendo "aqui o que eu quis dizer é…", coloque essa explicação no próprio diagrama.

Erros comuns

• Colocar tudo em um diagrama só. Contexto, deploy e detalhe de rede na mesma imagem: no fim, ninguém lê nada.
• Setas sem rótulo ou com duas pontas. Fica sem saber quem chama quem, e é exatamente isso que se procura durante um incidente.
• Níveis de abstração misturados. Se uma caixa é "Sistema de Pagamentos" e a do lado é "pod do Redis", o leitor perde a escala.
• Cores sem explicação. Cores que não estão na legenda são enfeite ou são mal interpretadas.
• Sem dono e sem data. Um diagrama na wiki sem autor conhecido acaba virando fonte de informação errada.

Mantendo o diagrama atualizado

Um diagrama só é útil enquanto as pessoas confiam nele. Alguns hábitos ajudam:

• Mantenha o diagrama perto da documentação do sistema e coloque o link no README ou no runbook.
• Inclua "diagrama atualizado?" no checklist dos pull requests que mudam a arquitetura.
• Guarde uma revisão antes de mudanças grandes, para que "como era no trimestre passado?" tenha resposta.
• Coloque uma revisão recorrente na agenda do time responsável, por exemplo uma vez por trimestre.

Como fazer um diagrama de arquitetura de software no Archboard

O Archboard é um espaço de trabalho de arquitetura hospedado na nuvem para times de plataforma e de produto. Os passos acima funcionam em qualquer ferramenta; no Archboard, eles ficam assim:

1. Entre. Use a página de login com sua conta Google ou GitHub. O primeiro login cria sua conta e sua organização; não precisa de cartão de crédito.
2. Escolha os packs. O Archboard tem 27 packs nativos com 223 tipos de nós. Para um primeiro diagrama, estes costumam bastar:
   • C4 Model: Person, Software System, Container, Component, Database e boundaries, para visões de contexto e de containers.
   • Kubernetes: Namespace (desenhado como frame), Deployment, Pod, Service, Ingress, ConfigMap, Secret, PVC, HPA, NetworkPolicy e outros.
   • Cloud: para infraestrutura de nuvem, incluindo um nó k8s-cluster para mapas com várias contas.
   • Network: para zonas de rede e conexões.
3. Conecte as portas. Os nós são nós de primeira classe com portas, não formas genéricas. Arraste uma conexão de porta a porta e rotule com protocolo e intenção.
4. Agrupe com frames. Use o Frame do pack Core para zonas de rede e regiões, o Namespace do Kubernetes para namespaces e os boundaries do C4 para o limite do sistema.
5. Adicione título e legenda. Coloque um bloco Markdown ou uma Table no canvas para reunir título, data, responsável e legenda em um só lugar.
6. Compartilhe. Envie o link público de compartilhamento para quem vai revisar (com a marca do Archboard no Free). No Pro e no Enterprise, você pode incorporar o diagrama no seu site de documentação via iframe.
7. Exporte. Exporte em SVG ou PNG (com marca d'água no Free); o Pro adiciona JPEG, PDF e GIF / WebM animados, tudo sem marca d'água. Também dá para exportar o documento do diagrama como JSON estruturado.

As alterações são salvas automaticamente e cada diagrama guarda revisões: as 5 últimas no Free, um ano de histórico no Pro e um histórico sem limite de tempo no Enterprise. O Free inclui todos os packs nativos, 3 diagramas e 15 nós de diagrama mais 150 notas, textos, figurinhas e tópicos de mapa mental por diagrama, mais do que suficiente para um primeiro diagrama de contexto; o Pro libera diagramas e nós ilimitados para mapas de implantação completos. Veja os detalhes em preços.

Antes de começar, explore a galeria de exemplos: abra um exemplo público e copie-o para o seu espaço de trabalho com Usar este exemplo (ele conta na sua cota de diagramas). Para detalhes de C4 e Kubernetes, veja as páginas de caso de uso C4 e caso de uso Kubernetes. As primeiras ideias também podem nascer no mesmo canvas: o Archboard tem sticky notes e mapas mentais ao lado dos packs de arquitetura.

Checklist e perguntas frequentes

Antes de publicar:

• Leitor e pergunta estão escritos
• O limite está claro e os sistemas externos são caixas únicas
• Toda seta tem direção e rótulo com protocolo + intenção
• Os grupos mostram limites reais: zonas de rede, namespaces, regiões
• Legenda, título, data e responsável estão presentes
• Alguém que não desenhou conseguiu responder à pergunta

Qual a diferença entre um diagrama de arquitetura e um fluxograma? Um diagrama de arquitetura mostra estrutura: quais componentes existem e como se conectam. Um fluxograma (flowchart) mostra os passos e pontos de decisão de um processo. Se a ordem de uma requisição no tempo importa, use um diagrama de sequência.

Quantos diagramas devo fazer? Um para cada par leitor-pergunta. Para a maioria dos sistemas, um diagrama de contexto, um de containers e um de deploy são um bom começo.

Qual ferramenta devo usar? Uma que conheça os conceitos que você desenha. O Archboard traz conceitos de Kubernetes, C4 e cloud como nós prontos com portas, então seu diagrama continua legível e fácil de manter atualizado. Seja qual for a escolha, o teste real é se o diagrama responde à sua pergunta.

Comece grátis — um seat, sem cartão de crédito.