Diagramas de arquitetura que não envelhecem: um fluxo de documentação viva

Toda organização de engenharia tem um: o diagrama de arquitetura na wiki que esteve correto por algumas semanas, anos atrás. Quem chega estuda o diagrama e depois descobre, por um colega, que metade das caixas foi renomeada e que a fila no meio foi substituída na primavera passada. A maioria das boas práticas de documentação de arquitetura foca no que desenhar. Este post trata da parte mais difícil: manter os diagramas corretos depois do primeiro rascunho, com um fluxo de trabalho que os trate como documentação viva, e não como entregáveis de uso único.

Por que a documentação de arquitetura fica desatualizada

Diagramas raramente envelhecem porque as pessoas são preguiçosas. Eles envelhecem porque o processo em volta deles torna isso o padrão.

• São entregáveis de uso único. Um diagrama é desenhado para uma revisão de design, o kickoff de uma migração ou uma auditoria. Depois da reunião, ninguém tem motivo para abri-lo de novo.
• Capturas de tela são coladas em todo lugar. O arquivo-fonte fica no notebook de alguém, e um PNG vai parar na wiki, no documento de onboarding, em três apresentações e em um README. Agora existem cinco cópias, e nenhuma pode ser editada.
• Ninguém é dono deles. “O time de plataforma” não é um dono. Quando ninguém específico é responsável, todo mundo supõe que outra pessoa vai atualizar.
• Nada dispara uma atualização. Mudanças de código passam por pull requests, revisão e CI. Diagramas só mudam quando alguém lembra, o que raramente coincide com o momento em que o sistema muda.
• Mostram coisa demais. Um diagrama com cada Pod, cada fila, cada role de IAM e cada jornada de usuário já está desatualizado no dia em que fica pronto, porque qualquer mudança em qualquer lugar o torna errado.

Nenhum desses é, antes de tudo, um problema de ferramenta; uma ferramenta de desenho melhor não resolve a falta de um dono. Mas a ferramenta pode tornar o fluxo certo barato ou caro.

Boas práticas de documentação de arquitetura para diagramas vivos

Este é o fluxo que recomendamos. Ele é opinativo de propósito.

1. Uma fonte única da verdade por diagrama

Cada diagrama existe em exatamente um lugar editável. Todo o resto é um link ou um embed apontando para esse lugar. Se você está prestes a exportar um PNG para colar em algum lugar, pergunte se um link resolveria. Geralmente resolve.

2. Linke, não copie

Wikis, sites de documentação e READMEs devem apontar para o diagrama vivo, e não conter uma imagem dele. Um diagrama incorporado ao vivo muda quando a fonte muda; uma captura colada fica errada para sempre depois da próxima mudança. Quando você realmente precisar de uma imagem estática, como um PDF para um auditor, trate-a como uma exportação datada e mantenha-a fora da documentação que as pessoas usam no dia a dia.

3. Defina um dono

Cada diagrama tem um dono: uma pessoa, ou um time com um ponto de contato nomeado. O dono não desenha cada mudança, mas é quem percebe quando algo está errado e quem recebe as perguntas. Coloque o dono no próprio diagrama e no seu índice de diagramas.

4. Ligue os gatilhos de atualização a eventos que já existem

Não dependa da memória. Associe atualizações de diagrama a eventos que já acontecem:

• Pull requests. Adicione ao template de PR uma caixa de seleção de impacto na arquitetura.
• ADRs. Cada architecture decision record aceito linka o diagrama que ele altera, e o diagrama é atualizado como parte da aprovação.
• Postmortems de incidentes. Se o incidente mostrou que o diagrama estava errado ou sem uma dependência, corrigi-lo vira um item de ação.
• Revisão trimestral. Os donos dedicam alguns minutos a cada diagrama para confirmar que ele ainda reflete a realidade e atualizam a data de “última revisão”.

Um trecho de template de PR:

## Architecture impact
- [ ] This change does not affect any architecture diagram
- [ ] I updated the affected diagram(s) and linked them below
- [ ] This needs an ADR (link):

5. Escolha o nível de detalhe certo

Use níveis em vez de uma única imagem gigante. O C4 model oferece um vocabulário comum: uma visão System Context (pessoas e sistemas), uma visão Container (aplicações e armazenamentos de dados) e uma visão Component dentro de um container. Níveis mais altos mudam pouco e são baratos de manter corretos. Níveis mais baixos mudam com frequência, então desenhe-os só onde as pessoas precisam e deixe o código ser a fonte da verdade abaixo disso.

Uma regra útil: se um diagrama muda a cada sprint, provavelmente ele foi desenhado um nível fundo demais.

6. Deixe data e versão visíveis

Coloque o dono e uma data de “última revisão” em um canto de cada diagrama. Assim, quem lê consegue avaliar a confiabilidade num relance: um diagrama revisado no mês passado e outro revisado há dois anos merecem níveis de confiança diferentes. Sem data, todo diagrama parece igualmente oficial, e isso é pior do que mostrar uma data antiga.

7. Mantenha um índice de diagramas

Uma página lista todos os diagramas que importam:

O índice deixa as lacunas visíveis (sem dono, data antiga) e é o ponto de partida natural para a revisão trimestral.

8. Combine diagramas com ADRs

Um diagrama mostra o que a arquitetura é. Ele não consegue mostrar por quê. Architecture decision records preenchem essa lacuna. O formato ADR original de Michael Nygard é curto o bastante para que as pessoas de fato escrevam: título, status, contexto, decisão, consequências. Linke o ADR no diagrama e o diagrama no ADR:

# ADR-019: Move payment events to a dedicated queue

## Status
Accepted

## Context
Payment events share a queue with notifications.

## Decision
Give payment events their own queue.

## Consequences
One more queue to operate. Diagram "Payments: containers" updated.

Quando alguém perguntar daqui a seis meses “por que está assim?”, a resposta estará a um clique.

Como o Archboard apoia um fluxo de documentação viva

O Archboard é um workspace de arquitetura hospedado na nuvem, e a maior parte do fluxo acima corresponde a recursos que ele já tem. Veja o que ele cobre e onde você ainda precisa do seu próprio processo.

• Fonte única da verdade. Cada diagrama é um único documento no seu workspace, com salvamento automático e snapshots de revisão. O Free guarda as últimas 5 revisões; o Pro guarda um ano de histórico de revisões e o Enterprise não tem limite.
• Linke, não copie. Todos os planos têm links públicos de compartilhamento (com a marca no Free). No Pro e no Enterprise você pode incorporar um diagrama no seu site de documentação via iframe, para que a página mostre a versão atual em vez de uma captura que fica para trás.
• Histórico no repositório. Exporte o diagrama como JSON estruturado e faça commit ao lado do código ou dos seus ADRs. Você ganha histórico no Git e uma etapa de revisão para mudanças de diagrama, além das revisões dentro do app. A exportação é manual, então faça dela parte da sua rotina de PR.
• Notas no canvas. Nós Markdown ficam no canvas, então o dono, a data da última revisão, os links para ADRs e uma legenda curta ficam dentro do diagrama, e não em um documento separado.
• O nível de detalhe certo. O pack C4 Model tem os nós Person, Software System, Container, Component e Database, além de boundaries. Os nós são nós de primeira classe com portas, e você os liga conectando as portas. Mantenha as visões context e container como diagramas separados.

Uma configuração concreta para um sistema:

1. Crie dois diagramas: “Payments: Context” e “Payments: Containers”.
2. Adicione no canto superior esquerdo um nó Markdown com o dono, a data da última revisão e links para os ADRs relacionados.
3. No Pro, incorpore a visão container na página de documentação do serviço. No Free, use o link de compartilhamento.
4. Quando um PR mudar a arquitetura, atualize o diagrama (ou deixe o agente de código que está trabalhando no PR fazer isso pelo servidor MCP do Archboard), exporte o JSON e faça commit em docs/architecture/ no mesmo PR.
5. Adicione os dois diagramas à sua página de índice.

Veja a visão geral do produto para o conjunto completo de recursos, o caso de uso C4 para configurações específicas de C4 e os preços para saber o que cada plano inclui. O Free oferece 3 diagramas, cada um com 15 nós de diagrama mais 150 notas, textos, figurinhas e tópicos de mapa mental, para você testar uma visão de contexto de um sistema; o Pro libera diagramas e nós ilimitados quando você documenta a plataforma inteira.

Checklist de documentação viva

• Cada diagrama tem exatamente uma fonte editável
• A documentação incorpora ou linka o diagrama vivo, sem capturas coladas
• Cada diagrama tem um dono nomeado, visível no diagrama
• O template de PR inclui uma caixa de impacto na arquitetura
• ADRs aceitos linkam os diagramas que alteram
• Postmortems perguntam “o diagrama ainda está certo?”
• Os donos revisam seus diagramas a cada trimestre e atualizam a data
• Os diagramas são separados por nível C4, e não em uma imagem gigante
• Um índice de diagramas lista nível, dono, data da última revisão e ADRs
• A fonte do diagrama (por exemplo, uma exportação JSON) está no repositório ao lado do código

Perguntas frequentes

Quantos diagramas um sistema deve ter? Comece com uma visão context e uma visão container. Adicione visões component só para as partes sobre as quais as pessoas perguntam com frequência. Poucos diagramas corretos valem mais do que muitos desatualizados.

Os diagramas devem ficar no repositório ou em uma ferramenta? Edite em um único lugar e mantenha o histórico onde seu time já revisa mudanças. Com o Archboard, você edita no canvas e faz commit da exportação JSON no Git.

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