Por que documentar arquitetura?
Documentação de arquitetura não é burocracia - é alavanca de velocidade. Sem ela, todo dev novo perde 2 a 4 semanas descobrindo como as coisas se conversam. Toda auditoria vira corrida contra o relógio. Toda decisão passada é reaberta porque ninguém lembra por que foi tomada.
O que documentar (o essencial, nem mais nem menos)
- Contexto do sistema: o que ele faz, para quem, e com quais sistemas externos conversa. É o C4 nível 1.
- Contêineres: aplicações, bancos, filas, gateways. C4 nível 2 - o coração da documentação.
- Decisões de arquitetura (ADRs): por que escolhemos Postgres e não MongoDB, por que Kafka e não RabbitMQ. Documento curto (1 página), datado, imutável.
- Dicionário de dados: tabelas principais, PII, retenção. Requerido por LGPD.
- Mapa de dependências externas: qual API de terceiro cai o sistema junto se ficar fora do ar.
Se você documentar só isso e mantiver atualizado, você já está no topo 10% dos times de engenharia do Brasil.
O problema real: documentação atualizada
A pergunta certa não é "o que documentar" - é "como impedir que a documentação apodreça". As tentativas típicas falham:
- Wiki interno (Confluence, Notion): ninguém abre, ninguém atualiza.
- Ferramenta visual (Lucidchart, drawio): o diagrama fica congelado em janeiro de 2023.
- PowerPoint de arquitetura: aparece em auditoria, some depois.
A raiz do problema é a separação entre código e documentação. Se estão em lugares diferentes, com donos diferentes, ciclos de revisão diferentes - a documentação vai perder.
A solução: documentação viva
Documentação viva significa que a documentação vive no mesmo repositório do código, é gerada a partir de arquivos declarativos, e cada mudança arquitetural passa obrigatoriamente por um PR que atualiza os dois juntos.
É a mesma ideia por trás de:
- OpenAPI / Swagger (documentação de API gerada do código).
- Storybook (documentação de UI gerada dos componentes).
- Diagrama como código (documentação de arquitetura gerada de arquivo texto).
Como o Excahub resolve isso
Você descreve seu sistema uma vez em ExcaFlow (um arquivo texto no seu repo). A partir dele o Excahub renderiza:
- O diagrama visual (C4 nível 2) sempre em dia.
- O README de arquitetura com contêineres e integrações.
- O dicionário de dados a partir dos nós de banco.
- O mapa de PII para relatórios de LGPD.
- O diff visual entre commits, direto no ExcaHub.
Uma fonte, várias saídas, tudo versionado no Git. Documentação de arquitetura deixa de ser um problema para virar consequência automática do processo de PR.