tekBlueprint

In today’s world of software development, architecture plays a key role in the success of a project, especially in large and complex systems. Architecture defines the structure of a system, its components, and their interactions. However, documenting architecture can be a labor-intensive task.

Methods for documenting architecture can vary from simple text descriptions to using specialized architecture models such as UML, C4, ArchiMate or SysML, depending on the adopted standards in the company or the preferences of the project teams. However, there are often problems with keeping such documents up-to-date and consistent with the real system.

In this context, the concept of Architecture as Code (AasC) appears, which proposes to use software development tools to manage architectural models. This allows automating the process of creating and maintaining architecture documentation, ensuring its relevance and consistency with the real system.

Architecture as Code (AasC)

Architecture as Code is an approach in which architectural models and technical documentation are described as source code. This allows you to take advantage of version control systems, automate processes, and integrate architectural documentation with the development process.

In my opinion, the following advantages of Architecture as Code can be highlighted:

1. Structured – templates of documents, diagrams, models, and description approaches are defined in a single style and are understandable to all participants in the process.
2. Consistency – architectural models are always up-to-date and consistent with the real system due to integration with the development process. Changes to the design documentation are made immediately and necessarily before changes in the solution being developed.
3. Change history – using version control systems allows you to track changes in the architecture, which is useful for analyzing changes that occurred throughout the entire development life cycle.
4. Accessibility – architects, analysts, and developers see the current picture of the world and work with the same artifacts.
5. Integration – easily integrate with CI/CD pipelines to automatically update documentation.

Tools for organizing the AasC approach

Of the main tools that I had to use, I would like to highlight the following:

1. PlantUML is a tool for creating UML diagrams using a simple text language. It supports a wide range of diagram types, including sequential, component, and class.
2. AsciiDoc is a text documentation format with markup support that can be used to create technical documentation, including diagrams.
3. Markdown – an easy-to-use markup format, ideal for quickly creating documentation.
4. Mermaid – is a JavaScript library for rendering diagrams and flowcharts from a simple text description. For custom diagrams.

All these tools can be used together or separately, depending on the needs of the project. They provided a variety of capabilities for creating diagrams and documentation, which made them valuable tools for developers and architects in their daily work.

Info

More details about this in a separate article about tools.

Structurizr

With all this, there was always one problem, it was necessary to build the documentation structure manually, with the rules for generating output documentation and publishing them. On the one hand, this is done once per project, but on the other hand, it takes time and effort. As an alternative, it is now possible to use Structurizr – this is a tool that allows you to automate the process of describing architecture (documentation, ADR, diagrams, relationships, etc.).

There is no particular point in describing the capabilities of Structurizr, everything is described in sufficient detail on the developer’s website. Most often, the lite version is used for a project, which provides basic functions and covers most of the needs.

An important point to remember is that diagram generation is performed through external services. For this reason, it is necessary to deploy additional services within the organization, since sending confidential project data to external services violates the NDA. To render diagrams without using external services, I’ve implemented a small plugin Structurizr: Diagrams Plugin that allows embedding diagrams generated offline as embedded images.