Documenting Application Modules

The application module model created via ApplicationModules can be used to create documentation snippets for inclusion into developer documentation written in Asciidoc. Spring Modulith’s Documenter abstraction can produce two different kinds of snippets:

C4 and UML component diagrams describing the relationships between the individual application modules
A so-called Application Module Canvas, a tabular overview about the module and the most relevant elements in those (Spring beans, aggregate roots, events published and listened to as well as configuration properties).

Additionally, Documenter can produce an aggregating Asciidoc file that includes all existing component diagrams and canvases.

Generating Application Module Component diagrams

The documentation snippets can be generated by handing the ApplicationModules instance into a Documenter.

Generating application module component diagrams using Documenter

Java
Kotlin

class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new Documenter(modules)
      .writeModulesAsPlantUml()
      .writeIndividualModulesAsPlantUml();
  }
}

class DocumentationTests {
    private val modules = ApplicationModules.of(Application::class.java)

    @Test
    fun writeDocumentationSnippets() {
        Documenter(modules)
            .writeModulesAsPlantUml()
            .writeIndividualModulesAsPlantUml()
    }
}

The first call on Documenter will generate a C4 component diagram containing all modules within the system.

Figure 1. All modules and their relationships rendered as C4 component diagram

The second call will create additional diagrams that only include the individual module and the ones they directly depend on the canvas.

Figure 2. A subset of application modules and their relationships starting from the order module rendered as C4 component diagram

Using Traditional UML Component Diagrams

If you prefer the traditional UML style component diagrams, tweak the DiagramOptions to rather use that style as follows:

Java
Kotlin

DiagramOptions.defaults()
  .withStyle(DiagramStyle.UML);

DiagramOptions.defaults()
  .withStyle(DiagramStyle.UML)

This will cause the diagrams to look like this:

Figure 3. All modules and their relationships rendered as UML component diagram

Figure 4. A subset of application modules and their relationships starting from the order module rendered as UML component diagram

Generating Application Module Canvases

The Application Module Canvases can be generated by calling Documenter.writeModuleCanvases():

Generating application module canvases using Documenter

Java
Kotlin

class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new Documenter(modules)
      .writeModuleCanvases();
  }
}

class DocumentationTests {

  private val modules = ApplicationModules.of(Application::class.java)

  @Test
  fun writeDocumentationSnippets() {
    Documenter(modules)
        .writeModuleCanvases()
  }
}

By default, the documentation will be generated to spring-modulith-docs folder in your build system’s build folder. A generated canvas looks like this:

Table 1. A sample Application Module Canvas
Base package	`com.acme.commerce.inventory`
Spring components	Services `c.a.c.i.InventoryManagement` Repositories `c.a.c.i.Inventory` Event listeners `c.a.c.i.InternalInventoryListeners` listening to `o.s.m.m.DayHasPassed`, `c.a.c.i.QuantityReduced` `c.a.c.i.InventoryOrderEventListener` listening to `c.a.c.o.OrderCanceled`, `c.a.c.o.OrderCompleted` Configuration properties `c.a.c.i.InventoryProperties` Others `c.a.c.i.InventoryItemCreationListener`
Aggregate roots	`c.a.c.i.InventoryItem`
Published events	`c.a.c.i.QuantityReduced` created by: `c.a.c.i.InventoryItem.decreaseQuantity(…)` `c.a.c.i.StockShort` created by: `c.a.c.i.InternalInventoryListeners.on(…)`
Events listened to	`c.a.c.o.OrderCompleted` `c.a.c.o.OrderCanceled`
Properties	`acme.commerce.inventory.restock-threshold` — `c.a.c.c.Quantity`. The threshold at which a `InventoryEvents.StockShort` is supposed to be triggered during inventory updates.

It consists of the following sections:

The application module’s base package.
The Spring beans exposed by the application module, grouped by stereotype. — In other words, beans that are located in either the API package or any named interface package. This will detect component stereotypes defined by jMolecules architecture abstractions, but also standard Spring stereotype annotations.
Exposed aggregate roots — Any entities that we find repositories for or explicitly declared as aggregate via jMolecules.
Application events published by the module — Those event types need to be demarcated using jMolecules @DomainEvent or implement its DomainEvent interface.
Application events listened to by the module — Derived from methods annotated with Spring’s @EventListener, @TransactionalEventListener, jMolecules' @DomainEventHandler or beans implementing ApplicationListener.
Configuration properties — Spring Boot Configuration properties exposed by the application module. Requires the usage of the spring-boot-configuration-processor artifact to extract the metadata attached to the properties.

Generating an Aggregating Document

When using Documenter.writeDocumentation(…) an all-docs.adoc file will be generated, linking all generated diagrams and Application Module Canvases. We can manually generate the aggregating document by calling Documenter.writeAggregatingDocument():

Generating an aggregating document using Documenter

Java
Kotlin

class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new Documenter(modules)
        .writeAggregatingDocument();
  }
}

class DocumentationTests {

  private val modules = ApplicationModules.of(Application::class.java)

  @Test
  fun writeDocumentationSnippets() {
    Documenter(modules)
        .writeAggregatingDocument()
  }
}

The aggregating document will include any existing application module component diagrams and application module canvases. If there are none, then this method will not produce an output file.