Hello! My name is Alexey. A couple of years ago, I started working on an open-source project called Archinsight. It has gained some attention within the community, and now I would like to share the reasons for undertaking this project and briefly outline future plans.
In the world of software engineering and the development of distributed microservices systems, precise architectural modelling plays a crucial role in defining the structure and relationships between system components. Many architects face the challenge of creating clear and precise architectural diagrams. An increasing number of companies tend to use tools such as PlantUML, which is widely used and powerful — one can create almost any diagram using it. However, this tool does not provide control over the integrity of the schema’s relationships — it draws everything you write leading to forgotten elements or connections leading nowhere. The consequences of this are inaccuracies and difficulties in analysing the relationships between components.
Why choose Archinsight over any other solution? First of all, it is very difficult to keep track of the flow of changes in the system and make necessary updates to interaction schemas. Second, many popular visualisation tools, such as PlantUML, do not ensure the integrity control of the developed diagrams. This leads to architects having to invent and constantly keep in mind a multitude of model development rules and limitations: the order of parameters in the declaration of schema elements, the need to create links to maintain interactivity of the diagram, not forgetting when adding element B to subsystem A diagram, add a backward link on the diagram of element B to reflect that changes. All of this requires significant effort in developing the architectural model and its accuracy. Moreover, it takes a ton of time to onboard a new architect in the team with all of the exceptions that newbie need to keep in mind…
In most companies where I have had the opportunity to work, the C4 methodology has been used to describe system architectures. This methodology, developed by Simon Brown, is designed to describe software architecture at different levels of abstraction. The C4 model consists of four levels: Context, Container, Component, and Code. Each level represents various aspects of architecture, starting from the general system context and ending with the implementation details of components.
We have always excelled in developing diagrams during the system design phase, but over time, these models began to lag behind the real state of affairs and lost their relevance. As a result, we decided to focus only on the Context and Container levels and not delve into more detailed descriptions. The accumulated experience has allowed me to realize that maintaining architectural diagrams in an up-to-date state cannot rely solely on the shoulders of software architects. It is necessary to actively involve analysts and developers in this work. And for this, it is necessary to provide them with a convenient tool that would take on most of the routine problems by linking and analyzing the developed diagrams.
Inspired by the need for such a tool, I decided to start developing Insight Language and the web editor Archinsight. Why did I choose not to adopt an existing and popular modelling language? The short answer is Because I can! I decided to create something akin to Python in the world of architectural modelling — a simple and easily understandable language for describing models without requiring extensive learning. That’s why I opted for managing the code structure using indentation and mandatory named parameters, sparing readers the pain of recalling which argument should be in the Storage element at the second position. Additionally, I endeavoured to minimise the number of control elements and the use of functional keys on the keyboard when working with model code.
Furthermore, I abandoned the necessity of declaring an element before its use in connections on the diagram. This decision alleviated many problems I faced while developing diagrams in PlantUML, as all described connections on the diagram had to be moved down the code, far from element declaration turning search into a nightmare. This solution allowed me to firmly bind the declaration of outgoing connections to the described element of the diagram, significantly improving file structure, searchability, and making the code more concise.
Currently, the project is in its early stages of development but already allows for the creation of Context and Container level C4 descriptions, controlling identifier declarations, schema element connectivity, and reusing existing elements through the import mechanism. The project enables users to register and create their repository for diagrams. Looking ahead, the main areas of focus for further development include:
- Advancing Insight Language by adding more translator checks, code introspections.
- Enhancing the web editor Archinsight by incorporating more automation of routine tasks and interactivity.
- Adding the ability to use a personal repository on GitHub in addition to Archinsight’s internal repository.
- Implementing features for team development, reviewing changes both at the code level and in the form of a visual diff of two diagrams.
- Maintaining Architecture Decision Records (ADR).
- Developing a plugin for IntelliJ IDEA.
- Designing API interfaces for creating plugins that could partially or fully automate the construction and validation of developed model.
You can evaluate the capabilities of the language and the editor in the Playground. I have prepared a set of language construction examples for you, which are used in the documentation, and maintain an open architectural description of the Archinsight project itself. You can try modifying an existing file or creating a new one. Don’t worry about losing your work — all source code will be saved in your browser’s local storage.
The project is published under the AGPL open-source license — you can access the source code, report bugs, provide feedback, explore the documentation or contribute in the project repository on GitHub: https://github.com/lonely-lockley/archinsight.