Collaborative Architecture Diagrams
Categories
Motivation
Architecture diagrams should be visible to everyone in the company, as Trust is one of our principles here at Empathy.co. Ensuring visibility would ensure we have a single source of truth where changes can be tracked and revisions can be made. It would also align Engineering, Growth, and Product teams, providing a common process for defining diagrams.
We have multiple diagrams for the various layers:
- Product Vision Diagram: made in Diagrams and owned by the Product team
- Architecture Logical Perspective: Miro diagram used to present architecture to customers and at workshops, focused on backend services
- Frontend Architecture Diagram: made in Diagrams and owned by Frontend teams
Some of the pain points:
- It is difficult to know where the diagrams are located
- Diagrams are not validated, so no there is no revision of the diagrams
- There is no set way of tracking changes
Proposal
Implementing a collaborative architecture diagram will make it easier to show how elements within Empathy.co interact with each other, by providing a wider view of the process. It’s key to have a single source of truth to improve collaboration and communication, avoid questions about where the latest version of each diagram is located, track changes, review new changes in the diagrams, and avoid uncertainty regarding how the elements are interconnected.
Although changes could be tracked using Confluence, by adding the diagrams to associated pages, we would prefer to have a way to review and validate the diagram before merging it. Therefore, our idea is to maintain the diagrams as code in GitHub, as it provides a code review for code changes.
Validation Changes
One difficult challenge is how to validate the changes in the current diagrams. Because the tools we use at present, Diagrams and Miro, are both located in the cloud, it can be a hassle to request, review, and accept changes.
Therefore, revision handling is required to roll back to the previous status if the changes are not accepted.
Editing diagrams in a repository could give us the same traceability as a code review, providing the ability to review diagram merge proposals easily and comment on them.
The merge requests can be made from localhost (which requires the Diagrams app to be installed on your computer) or from a web-based code editor following this guide.
The general architecture diagrams will be located in a centralized GitHub repo to maintain a single source of truth and avoid storing the diagrams in multiple locations.
The draw.io file needs to be saved in the repo and, from there, it’s easy to export to other formats, such as PNG, SVG, XML, etc. With the aim of showing the diagram as a snippet in markdown, the diagram needs to be saved in .svg format.
Plus, this approach allows engineers to add architecture diagrams into their repository, along with the microservices code. Doing so makes it easy for others to follow and review.
All Empathy.co employees are able to access the diagrams using their GitHub account, offering transparency, autonomy and the ability to work asynchronously. This change also allows for diagrams to be edited directly in GitHub with diagrams.net and github.dev.
The following video demo shows the simplicity and benefits of this approach.
Responsibilities
- Teams update the architecture diagram as part of the completion of a task
- The team proposes changes to the architecture diagram, which can be reviewed easily via pull request
- Design transforms the architecture diagram to provide more visual impact
- Growth requests design changes, if needed
- Engineering reviews the diagram from Design
- Engineering, Product, and Growth update the page, in the event that changes in the architecture diagram process occur
Summary
By using GitHub as a single source of truth for storing architecture diagrams, they will be saved in a centralized repository and be easily accessible to all members of the company. The Engineering department here at Empathy.co recommends using Diagrams.net or Excalidraw for building formal diagrams, but the important thing is to upload the source of truth to the repo. Opting for a centralized storage system will streamline the workflow and make finding and following architecture diagrams much simpler, offering company-wide visibility.
