Tá díficil? Quer que desenhe?

Uma coisa que todo dev sabe mas pouca gente fala abertamente: a maior parte da documentação técnica que a gente produz não é lida. Não porque as pessoas são preguiçosas, é porque texto corrido simplesmente não é o formato certo pra explicar arquitetura de software/infra para a maioria das pessoas.

Olha o Textão!

Pensa aquele projeto legado que você ficou dias tentando entender como as coisas se conectam. Lendo README desatualizado, abrindo arquivo por arquivo, tentando montar um mapa mental do sistema inteiro na cabeça.

Pior: quantas vezes você precisou apresentar uma proposta técnica pra alguém não-técnico e viu a pessoa perdida no meio da sua explicação?

A real é que nosso cérebro processa informação visual muito mais rápido que texto. Um diagrama de arquitetura bem feito comunica em 30 segundos o que um documento de 10 páginas tenta explicar. Isso não é opinião, é como a cognição humana funciona.

O ciclo vicioso da documentação

O que eu vejo acontecer em praticamente todo time:

1. No início do projeto, alguém faz uns diagramas feios no Draw.io ou Excalidraw
2. O projeto evolui, os diagramas ficam desatualizados
3. Ninguém atualiza porque não tem tempo
4. A documentação vira ficção, descreve um sistema que não existe mais
5. Dev novo entra no time e precisa descobrir tudo sozinho lendo código, texto e mais texto

Esse ciclo se repete porque manter diagramas atualizados manualmente é custoso demais. Você precisa abrir a ferramenta, lembrar onde cada coisa estava, reposicionar, reconectar... E quando tem pressa (sempre), a documentação é a primeira coisa que fica pra depois.

O elefante na sala: Agentes de IA

E agora temos um novo negócio (já nem tão novo assim) que tá se tornando cada vez mais comum. Hoje uma parte significativa do código sendo escrito em projetos não foi escrita por um humano. Cursor, Claude Code, Copilot, Windsurf, Devin — os agentes de IA estão gerando módulos inteiros, configurações de infra, pipelines, integrações. E tá funcionando. O software roda.

Mas aí vem a pergunta: Como esse código funciona?

Não estou falando de ler o código linha por linha — estou falando de entender a arquitetura que emergiu daquilo. Quais serviços foram criados, como eles se comunicam, onde estão as dependências, qual o fluxo de dados. Quando um agente monta uma aplicação inteira a partir de um prompt, o resultado pode ter dezenas de arquivos, múltiplas camadas, padrões que você não escolheu conscientemente.

Isso cria um tipo novo de código legado — um que nasce legado. Não porque é velho, mas porque ninguém que trabalha no projeto tem o mapa mental de como aquilo foi estruturado. O agente não deixou um diagrama de arquitetura pra trás. Ele entregou código funcional, comentários, .md e seguiu em frente.

Como saber realmente se aquilo está seguindo as melhores práticas? Com um diagrama, rapidamente você consegue visualizar os componentes, as conexões, as dependências — e aí sim decidir se o que o agente criou faz sentido, se precisa ser refatorado, ou se tem algum risco escondido ali que ninguém percebeu.

Ainda precisamos desconfiar da IA. É sobre manter a visibilidade sobre o que tá rodando em produção, independente de quem (ou o quê) escreveu o código.

O que eu tentei resolver

Eu passei um tempo pensando nisso, vendo como as equipes de desenvolvimento se debatiam para explicar como uma aplicação funciona (hoje trabalho principalmente com Segurança de Software) e comecei a construir no tempo livre o Flowabi, uma ferramenta de geração de diagramas de TI com IA. PS.: To precisando muito de feedback! Quem quiser testar!

A ideia central é simples: transformar rapidamente documentação complexa ou desatualizada em diagramas explicativos e editáveis.

Na prática, funciona assim:

Descreve o que quer, recebe o diagrama. Você escreve algo como "arquitetura de um e-commerce com React no front, Node no back, PostgreSQL, Redis pra cache e fila com RabbitMQ" e recebe um diagrama de arquitetura editável. Faça as mudanças que achar necessárias diretamente no diagrama, ou conversando com o assistente de IA.

Apresenta o código, vem o diagrama. Tem um código de infra (Terraform, Docker Compose, Kubernetes manifests) ou o próprio código da aplicação e quer entender visualmente como as coisas se encaixam? Manda o código (no Github ou na sua própria máquina) e transforma em diagrama. Esse desenho será especialmente útil pra onboarding de devs novos ou pra auditar infra que foi crescendo organicamente.

Manda uma imagem de diagrama, recebe ele editável. E aquele diagrama que alguém desenhou no quadro branco e tirou foto? Ou aquele screenshot de um diagrama antigo que ninguém tem o arquivo fonte? Você importa a imagem e transforma num diagrama que dá pra editar, atualizar e manter vivo.

Transforma documentação longa em visual. Aquele documento de 30 páginas descrevendo um fluxo de dados ou uma arquitetura de microsserviços? Alimenta o texto e extrai os diagramas relevantes. A informação já está lá — só precisa ser apresentada no formato certo.

Prototipa rápido com linguagem natural. Precisa rascunhar um diagrama de sequência pra uma reunião daqui a 15 minutos? Descreve o fluxo em texto e refina o resultado. É mais rápido que qualquer ferramenta drag-and-drop.

Qual a conclusão?

O Texto tem seu papel (com trocadilho), mas ele não é a melhor maneira de explicar as coisas para (a maioria) dos humanos. Num novo mundo de geração infinita de texto, código e conteúdo, as representações gráficas ganham cada vez mais relevância para entendermos o que está acontecendo.

A ferramenta é um MVP, ainda com muitas features para implementar. Agradeço muito um feedback sincero. Como vocês lidam com documentação de arquitetura hoje? Usam alguma ferramenta?

Segue novamente o link e muito obrigado: app.flowabi.com