O que é diagrama como código?
Diagrama como código (do inglês Diagram as Code ou Architecture as Code) é a prática de descrever a arquitetura de um sistema em um arquivo texto declarativo, versionado no Git, do qual o diagrama visual é renderizado automaticamente.
Em vez de arrastar retângulos numa ferramenta visual e salvar um .png, você escreve algo como:
node api "API REST" (server)
node db "Postgres" (database)
edge api -> db "query"E o canvas aparece. Se alguém muda o banco, faz PR no arquivo texto. Revisão obrigatória. Sem drift.
Por que engenharia sênior está migrando
- Versionamento real: git diff mostra exatamente o que mudou entre v3 e v4.
- Revisão em PR: mudar arquitetura vira commit revisável, não decisão de reunião.
- Zero drift: se o diagrama é gerado do código, ele nunca "esquece" de atualizar.
- Documentação automática: a partir do mesmo arquivo dá pra gerar README, dicionário de dados, mapa de dependências.
- Onboarding em minutos: novo dev clona o repo e vê a arquitetura viva na hora.
- Auditoria fácil: SOC2/ISO/LGPD pedem evidência de mudança - o git log é a evidência.
Diagrama como código vs. ferramenta visual: quando cada um faz sentido
Ferramenta visual clássica ganha em brainstorming inicial (quadro branco digital, 15 minutos, três pessoas rabiscando). Diagrama como código ganha em tudo que precisa durar mais de uma sprint: documentação oficial de sistema, modelagem de microserviços, revisão de arquitetura em PR, evidência de auditoria.
Como começar diagrama como código hoje
- Escolha um sistema pequeno para pilotar (não tente migrar o portfolio inteiro no dia 1).
- Descreva a arquitetura atual como texto: contêineres, bancos, filas, integrações externas.
- Coloque esse arquivo no mesmo repositório do código que ele descreve.
- Torne obrigatório: mudou infra, mudou o arquivo, PR revisado.
- Gere o diagrama a cada commit (CI/CD) para o README do projeto.
Por que Excahub?
O Excahub é a plataforma brasileira de diagrama como código. A sintaxe ExcaFlow foi desenhada para descrever arquitetura de software (não fluxograma genérico): você tem tipos nativos para banco, cache, fila, API, worker, gateway. O canvas é renderizado ao vivo enquanto você digita. Cada commit vira uma versão no ExcaHub, com diff visual entre versões.
E mais: a partir do mesmo arquivo, o Excahub gera README, dicionário de dados, mapa de PII (dados sensíveis) e até esboço de Terraform. Uma fonte, várias saídas - a definição literal de documentação viva.
Perguntas frequentes
Diagrama como código é a mesma coisa que IaC (Infrastructure as Code)?
Não. IaC (Terraform, Pulumi) descreve o que provisionar na nuvem. Diagrama como código descreve como o sistema se comunica - é uma camada acima. Idealmente os dois coexistem: o diagrama documenta o desenho, o IaC executa parte dele.
Preciso saber programar para usar diagrama como código?
A sintaxe do ExcaFlow é declarativa, mais parecida com YAML do que com programação. Se você já mexeu em docker-compose.yml, consegue.
Funciona para times não-técnicos?
O arquivo texto é para o time de engenharia. O diagrama renderizado é para todo mundo - product, jurídico, auditor. É o melhor dos dois mundos.