When I first came up with Archinsight, I wanted to solve a rather painful problem for IT architects: how to describe dozens (or even hundreds) of services and their interactions in such a way that diagrams, which many people work on, remain synchronized and do not cause confusion due to human error. Initially, in my project, I followed an obvious structured approach. It was tied to the levels of the C4 notation (Context, Container, etc.), where each level is described in its own file, and the need to write redundant, repeating blocks of code is eliminated via imports, while the linker ensures the diagram’s connectivity and correctness. It seemed logical: the diagrams are separated from each other, the code remains compact, and we can clearly see how one element is connected to another. But in practice, this turned out to be a set of fundamentally unsolvable problems for me, because the code describing, for example, a context and a container had to be synchronized in terms of identifiers and element descriptions; otherwise, consistency was lost. This demanded constant attention from users and required keeping multiple places updated in sync.
After some time, I realized that my initial approach was basically just a “somewhat smarter way to draw the same diagrams.” It doesn’t solve the core problem, namely the absence of a single, cohesive description of the system from which interconnected views at different levels of detail could be generated automatically. Users need to write the code once and magically get an overview of the context, details of containers or components — everything they need — without repeating code across different levels and with minimal risk of making a mistake.
Achieving this was not easy. I had to make a serious change to the Insight Language syntax, breaking a backward compatibility. I knew this was a radical step and that not everyone would like it. But the new approach ultimately provides much more flexibility and removes a number of inconveniences I personally encountered working with the first version. This allows us to move from an advanced way of describing diagrams to true architectural modeling.
Changes to the Language Structure
In the new version, the logic of describing a system still follows the C4 levels from top to bottom: starting with the bounded context (C4 Level 1), where we describe the systems, then moving on to the services (containers), and so on. However, the code that describes each new, more detailed level must now be placed inside the more general one. In other words, we treat the system as a whole and sequentially declare the nested entities needed for the next level of the diagram. Thanks to this hierarchical structure, the Insight language linker can now automatically build all relationships between components from the bottom up using data from the more detailed levels of the model. That wasn’t possible before: if something changed in a container, you had to remember where exactly those connections were specified in the context and be sure to update them manually.
Of course, you might ask, “What if the context includes multiple systems and the diagram becomes too large?” In the new version of the language, this is solved by allowing the single bounded context to be split into several files and still produce a unified diagram. At the context level, there is one shared diagram for all these files, but at the more detailed container level, only the part described in that file will be displayed.
For the import syntax, I opted for explicit declarations even if the systems in question belong to the same bounded context. It may seem excessive, but in practice it removes a lot of non-obvious “magic” around the visibility of identifiers declared in another file. Also, the Insight parser doesn’t rely on any specific file system structure: it doesn’t matter where the code files are stored, which allows users to organize the project directory structure as they wish, but at the same time does not allow one to easily see how model parts are linked. However, when you see explicit imports, you no longer have to wonder where some infrastructure component or external service suddenly came from in the diagram, and the new code navigation features let you quickly locate where it’s declared.
New Features
Another major improvement is enhanced interaction with the editor. Now there’s a separate tree view that displays the hierarchy of model elements, and a double-click lets you jump straight to the file and line where the element is declared.
This also works right from the diagram if you hold down Alt (on Windows) or Option (on macOS) and click the desired element. In other words, you can look at the diagram, see something interesting, and immediately drill down into the corresponding description. Previously, you had to rely on search to find where an element was declared.
Additionally, I added several new parameters to the description of relationships:
model— indicates the data model that a system or service uses in this interactionvia— for asynchronous communications, specifies which topic/channel of a message broker is used to deliver eventscall— for synchronous communications, lets you explicitly state which endpoint is called
They aren’t mandatory, but they greatly expand the possibilities for precisely describing what happens in these interactions. It becomes easier for users to navigate the diagrams, and the model is enriched with new data that can be used for subsequent C4 levels or for automatic analysis, which will definitely appear in Archinsight someday.
The Keyword external
The meaning of the external keyword has changed slightly. Previously, I assumed that a single file would describe both the current system and all its external dependencies, which led to a lot of repeated code. With the introduction of imports, all imported elements are now considered external to the current file by default, so the number of places where this keyword might be necessary has greatly decreased.
However, the external keyword itself remains and is now meant for any services or systems that do not belong to the modeled infrastructure. In the Archinsight Playground section, I created a context called external_systems in the file external.ai, where I placed external systems Google and GitHub. They can be imported from anywhere in the model, but they will always be marked as external systems, even on their own diagram. Thanks to the reflection feature, the Insight language linker will put all components that interact with these systems on their diagram, and the user can quickly see how deeply their project is integrated with external services by looking at a single diagram.
Minor Bugs in the Release
To be honest, there is one known issue: right now, the code editor requires that you add a newline at the end of the file, or it displays an error message on the last character.
It’s a rather annoying bug, and I haven’t yet found an elegant way to fix it. If you add a virtual EOL at the end of the file, it breaks code autocompletion and creates additional error messages that would be completely unclear to the user. You can read more about this in the related GitHub issue. For now, just be sure to add a newline at the end of the file.
I understand it’s not the prettiest solution, but I haven’t released any updates for a while, and I really wanted to finish work on version 2.0 so you can start using it and evaluate the new approach to architecture modeling. So I think it’s better to ship a working build now, while continuing to look for a fix to remove this defect.
Currently, archinsight.org is still running version 1.5.4. This is to inform users about the upcoming breaking changes and to give me time to update the language and project documentation, as well as launch the new website. As soon as everything is ready, version 2.0 will be released.
Light and Dark Themes in the Editor
Yes, they are here now, and they apply automatically based on your OS settings.
Why Do All This?
My main message is that keeping an architecture documentation up to date is a team effort: not only architects need this, but also analysts, developers, and everyone else who might need to quickly understand the system structure or make adjustments. If the tool requires a lot of training and manual work, and if each change requires updating multiple diagrams by hand, then the documentation will inevitably lag behind reality and contain many errors.
With Archinsight, I want to provide maximum automation, code reuse, and on-the-fly integrity checks. Yes, the new features may take some getting used to and break compatibility with the previous version. But in the long run, this approach eliminates repetitive code and genuinely removes obstacles to extending the capabilities of the Insight language, enabling the creation of models for large distributed systems — from the big idea down to the smallest infrastructure details.
Thank you for reading to the end — I hope my “roadmap” of changes and the reasons behind them will be useful to you. If you have any questions or suggestions, feel free to visit our repository on GitHub: you can report a problem there, join a discussion, or even help with the code. I believe that together we can make the development of architectural documentation even simpler and more engaging.