Living Documentation: Auto-generating C4 Diagrams with Spring Modulith

1. The Problem with Static Documentation and the C4 Model

The C4 Model is a fantastic standard created by Simon Brown to visualize software architecture across different zoom levels (Context, Container, Component, and Code). The problem is not the model itself, but maintaining it. If documentation takes too much effort and doesn’t reflect the code, developers stop trusting it.

Spring Modulith tackles the "Component" level (your logical modules) head-on. Because it intrinsically knows exactly who accesses what in your application (by analyzing package dependencies and dependency injections), it can generate structural diagrams that are guaranteed to be faithful to the codebase.

2. The Magic of the Documenter (In Practice)

Tip / The Real-World Problem: You don't need to install complex third-party tools to trace your architecture. You simply leverage the exact same unit test that validates your module rules (from our previous Modulith post) to generate the diagrams.

Add the documenter dependency to your pom.xml if you haven't already:

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

Next, create (or update) your architecture test:

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. Map the application modules
        ApplicationModules modules = ApplicationModules.of(Application.class);
        
        // 2. Create the documenter
        Documenter documenter = new Documenter(modules);
        
        // 3. Generate the global app diagram and focused individual module diagrams
        documenter.writeModulesAsPlantUml()
                  .writeIndividualModulesAsPlantUml();
                  
        System.out.println("C4/PlantUML diagrams generated successfully!");
    }
}

3. Essential Commands and Integration

When you run the test above (mvn test), Spring Modulith scans your application and generates .puml (PlantUML) files in the target/spring-modulith-docs folder.

What to do with these generated files?

• In IntelliJ IDEA or VSCode: Install the PlantUML extension. When you open the generated files, the IDEs render the diagram image instantly alongside the code.

• Continuous Integration (CI/CD): This is the true beauty of Docs as Code. In your GitHub Actions or GitLab CI pipeline, add a step that runs the tests and converts the .puml files into .svg or .png.

• Presentation: You can configure your pipeline to automatically update the repository's README or a GitHub Pages site. The code changes in a Pull Request -> the build runs -> the repository's architecture diagram updates itself!

Conclusion

Delegating the generation of structural documentation to the codebase is not just a cool trick; it is a sign of engineering maturity. With Spring Modulith's Documenter, your architecture, modules, and the events flowing between them become C4 and PlantUML diagrams without any manual drawing. Your code and documentation will never be out of sync again.