Documenting Microservices


Neil Laurance photoAt IG we have hundreds of Microservices; which presents a challenge: How does one effectively document their rapidly-evolving architecture?



Formal, 3rd party UML modelling tools invariably come with associated license and administration costs, and the problem that diagrams quickly diverge from reality over time (primarily because they exist apart from the systems they describe.) Application Performance Monitoring tools such as AppDynamics can help you stitch transactions together, thus documenting the actual linkages between services, but not the semantics. They only tell part of the story. What about domain models and interaction models?

We solve this problem by including diagrams with the code using PlantUML, a tool that lets you "write" diagrams instead of drawing them.

A typical PlantUML usage is as follows:

  • use the PlantUML plugin for Intellij to write the diagram with the output presented alongside it;
  • use the PlantUML plugin for Maven (plantuml-maven-plugin) to generate diagrams, and link to these from your Readme;
  • f​or some diagrams copy these into a PlantUML plugin available in our wiki (this is quite useful for diagrams not directly relating to a service).

As an example, the following code:
@startuml [*] --> PendingAccount : Application Form Completed state "Pending Account" as PendingAccount { state "Not Completed" as NotCompleted state "Needs Correction" as NeedsCorrection state "Manual Check" as ManualCheck [*] --> NotCompleted NotCompleted --down-> Verifying : Uploaded Verifying -up-> NotCompleted : Verified Verifying --down-> ManualCheck : Not Verified ManualCheck -up-> NotCompleted : Manually\nVerified NotCompleted --down-> NeedsCorrection : Error NeedsCorrection --> NotCompleted : Manually\nCorrected NotCompleted --right-> Completed : All Required\n Documents Verified Completed -----> [*] } PendingAccount --> [*] : All Pending Account Processes Completed @enduml
Produces the following diagram:
Plant UML Example Picture

This has a number of benefits:

  • the tool is free;
  • diagrams are under the same version control as your code;
  • all members of the team can easily contribute to these diagrams; and
  • writing diagrams are quicker than drawing, because you stop worrying about the exact layout.

The last point is a strength but also a weakness, as above a certain size, PlantUML diagrams become unwieldy, however for our microservices they have proven to be a very effective architecture documentation tool.

About the author:

Neil joined IG in 2011, and became Chief Technical Architect in 2012. He has overseen the migration from a monolithic to a microservices architecture to reduce risk and empower autonomous teams. He is a keen advocate of continuous delivery principles, and has supported their adoption within IG. Find him on LinkedIn.