An approach to build consistent software architecture diagrams using devops system descriptors

Abstract

System architecture diagrams play an essential role in understanding system architecture. They encourage more active discussion among participants and make it easier to recall system details. However, system architecture diagrams often diverge from the software. As a result, they can interfere with the understanding and maintenance of the software. We propose an approach to build system architecture diagrams using DevOps system descriptors to improve the consistency of architecture diagrams. To produce our approach, we survey problems with architecture diagrams in the software industry, developing guidelines for creating architecture diagrams. Next, we produce a taxonomy for system descriptor concepts and a process to convert system descriptors into architecture diagrams. We evaluate our approach through a case study. In this case study, we defined a Docker Compose descriptor for a newsfeed system and transformed it into a system architectural diagram using the proposed approach. Our results indicate that, currently, system descriptors generally lead to consistent diagrams only to a limited extent. However, the case study's observations indicate that the proposed approach is promising and demonstrates that system descriptors have the potential to create more consistent architectural diagrams. Further evaluation in controlled and empirical experiments is necessary to test our hypothesis in more detail.