Template de documentação de arquitetura de software (grátis)

O jeito como um documento de arquitetura costuma nascer: um engenheiro novo entra, pergunta como as peças do sistema se encaixam, e alguém promete "documentar direito". Essa pessoa procura um template de documentação de arquitetura de software, encontra um arquivo Word de quarenta páginas de 2012 ou um PDF de universidade, preenche metade e nunca mais abre. Um ano depois, o próximo recém-contratado encontra o documento, confia nele e se engana.

O problema raramente é a falta de um template. São templates que pedem tudo, e aí nada é terminado, e documentos sem dono, e aí nada é atualizado. O template abaixo é enxuto de propósito: um único arquivo markdown, nove seções, cada uma presente porque quem ler vai precisar dela. Copie para o seu repositório, sem cadastro, sem download. Depois leia as notas seção por seção sobre o que colocar em cada parte e como evitar que ele fique desatualizado.

Para que serve um documento de arquitetura (e quem o lê)

Um documento de arquitetura responde às perguntas que o código não responde rápido: para que serve o sistema, com o que ele conversa, como ele é dividido, por que é dividido assim e o que se sabe que é frágil. Ele não é a especificação de design de uma funcionalidade, e não é uma referência de API.

Ele tem cinco tipos de leitor, e ajuda escrever pensando em cada um pelo nome:

Se uma seção do seu documento não serve a nenhum deles, apague. Essa regra faz mais pela qualidade da documentação do que qualquer template.

Uma nota sobre nomes: "documento de arquitetura", "system design document" (SDD) e "software architecture document" (SAD) são usados para mais ou menos a mesma coisa. Templates de SDD costumam ser escritos por projeto ou por funcionalidade e incluem o design detalhado; um documento de arquitetura descreve o sistema como ele é e muda junto com ele. O template aqui é do segundo tipo.

O template (um único bloco markdown)

Copie isto para docs/architecture.md (ou ARCHITECTURE.md na raiz) e preencha. Tudo o que está entre sinais de menor e maior é um espaço reservado. Apague qualquer seção que não se aplique em vez de deixá-la vazia.

# <Nome do sistema>: arquitetura

| | |
|---|---|
| Dono | <equipe ou pessoa responsável por manter isto verdadeiro> |
| Última revisão | <AAAA-MM-DD> |
| Próxima revisão | <AAAA-MM-DD, ou "a cada mudança nas seções 3-5"> |
| Status | <rascunho / atual / sendo substituído por X> |

## 1. Contexto e escopo

<Duas ou três frases: o que o sistema faz, para quem e por que existe.>

**Usuários**
- <Papel>: <o que fazem com o sistema>

**Sistemas externos**
- <Sistema>: <o que enviamos ou recebemos, protocolo>

**Fora do escopo**
- <Coisas que as pessoas supõem que este sistema faz, mas ele não faz>

**Diagrama de contexto de sistema (C4 nível 1)**
<Link ou embed. O sistema como uma caixa, todos os tipos de usuário, todos os sistemas externos.>

## 2. Objetivos de qualidade

As três a cinco qualidades que prevalecem quando entram em conflito entre si, em ordem de prioridade.

| Prioridade | Qualidade | Cenário concreto |
|---|---|---|
| 1 | <ex.: Disponibilidade> | <ex.: O checkout continua funcionando quando o serviço de recomendações está fora do ar> |
| 2 | <ex.: Latência> | <ex.: checkout p95 abaixo de 2 s com 500 pedidos/minuto> |
| 3 | <ex.: Modificabilidade> | <ex.: Um novo meio de pagamento entra em produção sem tocar no order service> |

## 3. Restrições

Coisas que não escolhemos, mas com as quais temos de conviver.
- <ex.: Roda na plataforma Kubernetes da empresa>
- <ex.: Os dados dos clientes ficam na UE>
- <ex.: Serviços de backend apenas em Go ou Java>

## 4. Arquitetura

**Diagrama de containers (C4 nível 2)**
<Link ou embed. Cada unidade implantável e cada armazenamento de dados, com tecnologia e protocolos.>

| Container | Tecnologia | Responsabilidade | Dono |
|---|---|---|---|
| <Web app> | <SPA React> | <O que faz> | <Equipe> |
| <API> | <Go> | <O que faz> | <Equipe> |
| <Banco de dados> | <PostgreSQL> | <O que armazena> | <Equipe> |

**Diagramas de componentes (C4 nível 3)**
<Apenas para o um ou dois containers com que um recém-chegado teria dificuldade. Link ou embed.>

**Fluxos principais**
<Os dois ou três cenários mais importantes, como passos numerados ou como diagrama dinâmico C4.>

1. <Ator> -> <Container>: <o que acontece>
2. <Container> -> <Container>: <o que acontece, protocolo, síncrono ou assíncrono>

## 5. Decisões-chave

Os registros completos ficam em <docs/adr/>. Este é o índice.

| ADR | Decisão | Status | Data |
|---|---|---|---|
| [ADR-001](adr/001-<slug>.md) | <ex.: Um banco de dados por serviço> | Aceito | <AAAA-MM-DD> |
| [ADR-002](adr/002-<slug>.md) | <ex.: Kafka para eventos de pedido> | Aceito | <AAAA-MM-DD> |

## 6. Aspectos transversais

Como o sistema inteiro lida com as coisas que todo container toca. Uma ou duas linhas cada, com um link para o detalhe.
- **Autenticação e autorização:** <onde acontece, qual token>
- **Observabilidade:** <logs, métricas, traces, onde olhar>
- **Tratamento de erros e retries:** <convenções, idempotência>
- **Dados e privacidade:** <onde ficam os dados pessoais, retenção>

## 7. Deployment e operação

- **Ambientes:** <produção, staging, ...> e como diferem
- **Onde roda:** <cloud, região, cluster>
- **Runbooks:** <link>
- **Dashboards e alertas:** <link>

## 8. Riscos e dívida técnica

| Risco ou dívida | Impacto se acontecer | Plano | Dono |
|---|---|---|---|
| <ex.: Estoque reservado antes do pagamento, sem compensação> | <Reservas fantasmas depois de falhas de pagamento> | <Adicionar liberação em caso de falha, Q4> | <Equipe> |

## 9. Glossário

| Termo | Significado aqui |
|---|---|
| <Pedido> | <Definição como o negócio usa> |

Esse é o template inteiro. Preenchido para um sistema com uns dez containers, ele costuma ocupar algumas páginas. Se o seu fica muito mais longo, provavelmente algo nele pertence a um documento vinculado, e não a este.

Seção por seção

Cabeçalho: dono e data de revisão

As quatro linhas do topo importam mais do que qualquer seção abaixo delas. Dono diz quem corrige o documento quando ele está errado. Última revisão diz ao leitor o quanto confiar nele. Um documento que diz "última revisão há catorze meses" é honesto; um que não diz nada parece atual quando não é.

1. Contexto e escopo

Comece por aqui, porque todas as outras seções dependem da fronteira. Liste todos os tipos de usuário e todos os sistemas externos, inclusive os que você dá como certos (provedor de identidade, serviço de e-mail, gateway de pagamento). A lista fora do escopo economiza mais reuniões do que qualquer outra parte do documento: é onde você registra que este sistema não trata reembolsos, mesmo que todo mundo ache que sim.

O diagrama é um diagrama de contexto de sistema C4: o seu sistema como uma caixa, usuários e sistemas externos ao redor, setas com rótulos. O guia do diagrama de contexto de sistema explica o que entra nele.

2. Objetivos de qualidade

A maioria dos documentos de arquitetura pula esta seção, e ela é a que explica todo o resto. "Disponibilidade acima de consistência" ou "modificabilidade acima de desempenho bruto" diz ao leitor por que os containers têm essa cara. Fique entre três e cinco objetivos, ordene-os e dê a cada um um cenário concreto o bastante para ser testado: um número, uma carga, uma falha.

3. Restrições

Restrições são as decisões que outra pessoa tomou: o time de plataforma, o jurídico, a política de linguagens da empresa. Registrá-las encerra a conversa do "por que você não usou simplesmente X?" e diz a um leitor futuro quais escolhas podem ser revistas e quais não.

4. Arquitetura: os diagramas C4

Esta é a seção que a maioria das pessoas entende como "a arquitetura". Use o modelo C4, porque ele dá a cada diagrama uma única função:

• Diagrama de containers (nível 2), sempre. Cada unidade implantável e cada armazenamento de dados, cada um com sua tecnologia, cada seta com um protocolo. Se você só for desenhar um diagrama, desenhe este. O guia do diagrama de containers tem um exemplo completo.
• Diagramas de componentes (nível 3), de forma seletiva. Apenas para os containers com que um recém-chegado teria dificuldade.
• Fluxos principais. Dois ou três cenários como passos numerados. Um diagrama estático mostra que dois containers conversam; um fluxo mostra em que ordem, e por quais passos o usuário espera. O guia do diagrama dinâmico C4 mostra como escrever um.

A tabela de containers com uma coluna Dono está lá de propósito. Um container que não tem dono é um container que ninguém vai atualizar neste documento também.

Se o C4 é novidade para você, o que é o modelo C4 explica os quatro níveis. Para exemplos desses diagramas aplicados a sistemas reais e grandes, veja nossos exemplos de modelo C4.

5. Decisões-chave (ADRs)

Não escreva as decisões no corpo do texto. Mantenha cada uma como um architecture decision record em arquivo próprio (contexto, decisão, alternativas consideradas, consequências) e deixe aqui apenas o índice. ADRs são escritos uma vez e substituídos em vez de editados, então o documento continua curto e o histórico continua intacto. O guia completo de architecture decision records cobre o formato e quando uma decisão merece um.

Um bom teste para o índice: um engenheiro novo deveria conseguir apontar para qualquer caixa surpreendente da seção 4 e encontrar o ADR que a explica.

6. Aspectos transversais

Algumas coisas não vivem em um único container: autenticação, logging, tratamento de erros, onde ficam os dados pessoais. Uma ou duas linhas para cada uma bastam, com um link para o detalhe. É nesta seção que um auditor passa a maior parte do tempo, então facilite a vida dele.

7. Deployment e operação

Mantenha curta e aponte para fora. Os ambientes e como diferem, onde o sistema roda, e links para runbooks e dashboards. O detalhe pertence ao seu código de infraestrutura e aos seus runbooks, que mudam com mais frequência do que este documento deveria mudar.

8. Riscos e dívida técnica

A seção honesta. Registre o que se sabe que é frágil, com um dono e um plano, mesmo que o plano seja "aceito, rever no Q3". Um risco registrado é um risco que alguém pode priorizar. Um risco que vive na cabeça de um engenheiro vai embora com ele.

9. Glossário

Todo sistema tem palavras que significam algo específico ali: "pedido" vs "carrinho", "conta" vs "tenant", "atendimento". Defina cada uma uma única vez. Engenheiros novos leem esta seção mais do que você imagina.

Como isto se relaciona com o arc42

Se este template parece familiar, é porque é um recorte enxuto das mesmas ideias do arc42, o template gratuito e open source de documentação de arquitetura criado por Peter Hruschka e Gernot Starke. O arc42 tem doze seções e ele mesmo aconselha documentar "apenas o que seus stakeholders precisam" (FAQ do arc42, B-1). O mapeamento:

Escolha o arc42 quando precisar da estrutura completa dele: ambientes regulados, sistemas grandes com vários arquitetos, ou uma organização que já o adota como padrão. Escolha algo deste tamanho quando a alternativa for não ter documento nenhum. Para uma comparação detalhada, incluindo qual diagrama C4 vai em qual seção do arc42, veja arc42 vs C4.

Evitando que ele fique desatualizado

Todo documento de arquitetura está correto no dia em que é mesclado. Se ele ainda estará correto daqui a seis meses depende de alguns hábitos, a maioria deles sobre os diagramas, porque as seções 4 e 5 são onde a realidade muda mais rápido.

Mantenha-o no repositório. docs/architecture.md ao lado do código significa que um pull request que divide um serviço pode atualizar a tabela de containers na mesma revisão. Uma página de wiki não pode fazer parte de um code review.

Vincule diagramas, não cole capturas de tela. Uma captura de tela do diagrama de containers fica desatualizada no momento em que um container é renomeado. Um diagrama renderizado a partir de um modelo (Structurizr DSL, um modelo YAML ou uma ferramenta que guarde um) só fica tão desatualizado quanto o modelo.

Coloque a data de revisão para trabalhar. Adicione o documento a qualquer checklist que rode quando um container é adicionado ou removido: o template de pull request, a revisão de arquitetura, o planejamento trimestral. "Próxima revisão: a cada mudança nas seções 3 a 5" é uma entrada válida.

Escreva as decisões para frente. Nunca edite um ADR aceito. Substitua-o. O índice da seção 5 passa então a mostrar o histórico, que é a parte de que as pessoas mais precisam.

Verifique as partes estruturais automaticamente. As seções 1 e 4 descrevem coisas que existem no código: serviços, armazenamentos de dados, dependências. Essas podem ser comparadas com o repositório. As seções 2, 6 e 8 não podem, e precisam de uma pessoa com periodicidade definida. O guia de detecção de architecture drift cobre os métodos para o primeiro tipo e o que cada um consegue e não consegue enxergar.

Esse é o problema para o qual o archyl foi feito, na metade do documento que é feita de diagramas. Conecte um repositório e a descoberta por IA propõe o modelo C4 (sistemas, containers, componentes e relacionamentos) para você revisar e aprovar em vez de desenhar. ADRs, documentação e fluxos se ligam aos elementos que descrevem. Um drift score então verifica se os elementos documentados ainda existem no código, de forma determinística e sem IA no caminho, então uma seção 4 desatualizada aparece como um número e não como uma surpresa. Ele não verifica seus objetivos de qualidade nem sua lista de riscos; esses ainda precisam da data de revisão. Para as práticas que mantêm a documentação atualizada com ou sem ferramenta, veja documentação de arquitetura viva.

FAQ

O que um documento de arquitetura de software deve incluir?

No mínimo: o contexto e o escopo do sistema (usuários e sistemas externos), um diagrama em nível de containers com as tecnologias, as decisões de arquitetura principais com suas razões, os riscos conhecidos e um dono com uma data de revisão. O template acima acrescenta objetivos de qualidade, restrições, aspectos transversais, notas de deployment e um glossário, todos curtos.

Este template é mesmo gratuito?

Sim. É o bloco markdown acima. Copie e adapte ao seu sistema. Sem cadastro, sem download, sem e-mail.

Onde o documento de arquitetura deve ficar?

No repositório, como docs/architecture.md ou ARCHITECTURE.md, ao lado dos ADRs em docs/adr/. Assim, as mudanças na arquitetura e as mudanças no documento passam pelo mesmo pull request.

Qual deve ser o tamanho de um documento de arquitetura?

O mais curto possível sem deixar de responder às perguntas dos seus leitores. Para um sistema com uns dez containers, algumas páginas é o normal. Se ele crescer muito além disso, mova o detalhe para documentos vinculados (runbooks, ADRs, referências de API) e mantenha este como o mapa.

Qual é a diferença entre isto e um system design document?

Um system design document geralmente é escrito para um projeto ou uma funcionalidade, antes de ser construído, e inclui o design detalhado. Um documento de arquitetura descreve o sistema inteiro como ele é agora e muda junto com ele. As equipes costumam ter um documento de arquitetura por sistema e muitos design documents ao longo da vida dele, com as decisões duradouras dos design documents virando ADRs.

Devo usar o arc42 no lugar deste?

Se você precisa da estrutura completa dele ou se sua organização já o usa, sim. Este template se relaciona com as seções do arc42 (veja a tabela acima), então você pode começar por aqui e migrar para o arc42 depois sem reescrever nada.

Quer que os diagramas da seção 4 venham do seu código e não da memória? Experimente o archyl grátis no plano Developer, sem cartão de crédito. Continue lendo: arc42 vs C4 | Architecture Decision Records: o guia completo | O que é o modelo C4? | Documentação de arquitetura viva | Detecção de architecture drift.