Documentação Viva: Gerando Diagramas C4 Automaticamente com Spring Modulith

1. O Problema da Documentação Estática e o C4 Model

O C4 Model é um padrão fantástico criado por Simon Brown para visualizar a arquitetura de software em diferentes níveis de zoom (Contexto, Container, Componente e Código). O problema não é o modelo, mas sim a manutenção dele. Se a documentação dá trabalho e não reflete o código, os desenvolvedores param de confiar nela.

O Spring Modulith ataca exatamente o nível de "Componentes" (seus módulos lógicos). Como ele sabe exatamente quem acessa o quê na sua aplicação (analisando as dependências de pacotes e injeção de dependências), ele é capaz de gerar o diagrama estrutural de forma garantidamente fiel ao código.

2. A Mágica do Documenter (Na Prática)

Dica / O Problema do Mundo Real: Você não precisa instalar ferramentas complexas para rastrear a arquitetura. Basta aproveitar o mesmo teste unitário que já valida as regras dos seus módulos (visto no post de Spring Modulith) para gerar os diagramas.

Adicione a dependência do documentador no seu pom.xml se ainda não tiver:

<dependency>
    <groupId>org.springframework.modulith</groupId>
    <artifactId>spring-modulith-docs</artifactId>
    <scope>test</scope>
</dependency>

Em seguida, crie (ou atualize) o seu teste de arquitetura:

package com.alexsousadev.app;

import org.junit.jupiter.api.Test;
import org.springframework.modulith.core.ApplicationModules;
import org.springframework.modulith.docs.Documenter;

class ArchitectureDocumentationTests {

    @Test
    void generateC4Diagrams() {
        // 1. Mapeia os módulos da aplicação
        ApplicationModules modules = ApplicationModules.of(Application.class);
        
        // 2. Cria o gerador de documentos
        Documenter documenter = new Documenter(modules);
        
        // 3. Gera o diagrama geral da aplicação e diagramas focados para cada módulo
        documenter.writeModulesAsPlantUml()
                  .writeIndividualModulesAsPlantUml();
                  
        System.out.println("Diagramas C4/PlantUML gerados com sucesso!");
    }
}

3. Comandos e Integração Essenciais

Quando você roda o teste acima (mvn test), o Spring Modulith escaneia sua aplicação e gera arquivos .puml (PlantUML) na pasta target/spring-modulith-docs.

O que fazer com esses arquivos gerados?

• No IntelliJ IDEA ou VSCode: Instale a extensão PlantUML. Ao abrir os arquivos gerados, as IDEs renderizam a imagem do diagrama instantaneamente ao lado do código.

• Integração Contínua (CI/CD): A verdadeira beleza do Docs as Code. No seu pipeline do GitHub Actions ou GitLab CI, adicione um passo que roda os testes e converte os .puml em .svg ou .png.

• Apresentação: Você pode configurar o seu pipeline para atualizar o README do repositório ou um portal no GitHub Pages automaticamente. O código muda no Pull Request -> o build roda -> o diagrama de arquitetura do repositório se atualiza sozinho!

Conclusão

Delegar a geração da documentação estrutural para o código não é apenas um truque legal, é maturidade de engenharia. Com o Documenter do Spring Modulith, a sua arquitetura, os módulos e os eventos que transitam entre eles viram diagramas C4 e PlantUML sem nenhum esforço manual. O seu código e a sua documentação nunca mais estarão desalinhados.