Automatic UML Sequence Diagram Generation for Elixir/Phoenix Applications

2 min readDec 24, 2021

Documenting business logic of a service and keeping it up to date is one of the most complex tasks in the software development. Sequence diagrams have been a very useful tool to achieve this task but their creation takes some effort and they get out to date pretty fast.

This repository offers an automated way of doing this based on logs of api calls with the goal to have an automated way to generate sequence diagrams and keep them up to date with less effort.

The project contains a simple phoenix project with a controller that makes 3 simple API calls, the PUML generator that generates PUML files and together with a script, generates the sequence diagrams.

The following sequence diagram is automatically generated from page_controller_test.exs:

About the implementation

the generation is based on Logs from Logger, Plug.Logger, PumlGenerator.PumlLogger and the hackney debug logs
the logs are collected by the PumlBackend, translated into PUML items and stored in the ETS cache
a post-processor sets the PUML participants to the items and marks each item as public or internal based on the url_participant_map
at the end of the process the PUML is written as a file to the configured path
together with the macros in the puml_lib the final sequence diagrams can be generated

In my experience every business case is different and has very specific requirements so that making a generic library would be something pretty difficult to maintain. Therefore I decided to share just the functionality in the repo ;)

Getting started

Preconditions:

elixir 1.12
java 8

Commands:

clone repo
mix test && ./generate_puml.sh

Integration into other projects

copy the puml_generator_lib folder to your project
add plug(PumlGenerator.PumlLogger) to endpoint.ex
use PumlGenerator.Generator in your integration test parametrized as described in Parameters.
the configuration will be the heart of your diagrams, specially the url_participant_map
use the methods from PumlGenerator.Generator to log start, end, opt-start, opt-end, webhooks and SQS messages in your integration test
enable generator by setting environment variable GENERATE_PUML=true
run your specific test
the PUML is created in the configured path
modify the script generate_puml.sh to generate png and svg with and without internal calls of the generated puml

Example

Configuration

config :puml_generator, PumlGenerator.Generator, 
 allowed_url_parts: ~w(amazing_service google.com yahoo.com status customer.com webhook_endpoint), 
 allowed_request_params: ~w(somedata moredata data),    
 allowed_response_params: ~w(somedata data), 
 value_params: ["data"], self: "amazing_service", 
 actor: "customer", 
 public: "serious_service_name", 
 participants: [ 
  {"amazing_service", "AmazingService"}, 
  {"tp", "ThirdParty"} 
  ], 
 url_participant_map: [ 
  {"/status", :self, "tp", true}, 
  {"yahoo", :self, "tp", true}, 
  {"amazing_service", :actor, :self}, 
  {"/webhook_endpoint", :self, :actor} 
 ]

Usage

use PumlGenerator.Generator 
test "my test", %{conn: conn} do 
  record_puml(path: "process.puml") 
  do_interesting_stuff()   puml_opt_start("optional part") 
  do_optional_stuff() 
  puml_opt_end()   end_interesting_stuff() 
  save_puml() 
end

If you liked this post, please follow me. I would be very grateful ;)

Originally published at https://github.com/felipeloha/puml_generator