Lessons learned from creating architecture visions and blueprints
How to make usable architecture visions and blueprints?
During several enterprise architecture mandates, we at ELCA have helped our customers create architecture visions and blueprints. Often, we have encountered differences of opinion within the team about what these artefacts should contain and how they should be used later. We have noticed that if this discrepancy is not resolved, there is a risk that the results of the architecture visions and blueprints will be of little value and will not fully fulfill the intended objectives.
I would like to share our experiences and insights of creating architecture visions and blueprints and examples of the possible outcomes from the enterprise architecture mandates and how to use them.
The goal of creating these architectural artefacts is to achieve a common understanding between the parties involved and to create a basis for an application landscape that remains maintainable in the long term. To reach this goal, from our experience at ELCA, the 3 most important aspects for succesfully creating these artefacts are
- Agree about the target group(s) and suitable level of details for each stakeholder-group
- Agree about the scope and integration to other processes
- Agree about the usage, roll-out and maintenance
In this article I’ll answer to following questions:
- Which benefit do these artitectural artifacts bring?
- What are examples of these artefacts?
- What to consider when creating them?
- What risks can be faced and how to handle them?
Let’s dive in to more details and start with the usual WHY and WIIFM (What’s in it for me).
Why architecture vision and architecture blueprint are helpful?
When starting a new application, it may indeed sound easy to start the project from scratch with an existing small team, almost with the spirit of a start-up: take ownership, be independent. However, in a larger company with a number of these island applications, there may be redundancies or differences:
- Redundancy in data and functionality
- Differences in technology
Let’s have a look at common application features. From my experience, business applications tend to have a some aspects in common, for example:
- Permission management
- Reporting
- Visualization of the data
- Forms to fill with validation rules
- Workflow to follow
- Interfaces to other systems
- Search
When applications are built independently, the same or similar functionality may be implemented multiple times using different technologies. Side note: In a micro-service architecture, different technologies are quite welcome. However, in an application landscape, I recommend that similar requirements, such as search, are implemented in the same way, e.g., by using Elastic Stack or SQL full-text search instead of having many different implementations.
Below an image of two imaginary applications as a separated island applications and with applied target architecture. The dark colored part is application specific, the light colored is shared. In the second image it is visible, that less specific components are needed.
So, how can architecture vision or architecture blueprint help in this case?
For architecture vision the usual definition is from TOGAF, which describes it quite high level: “mission, vision, strategy, goals”, “first-cut, high-level description of the baseline from a business and a technical perspective”. In my opinion, the architecture vision should set the direction and define the constraints for the application landscape, so that the development of a new application or service can start faster as the initial discussions are shorter. For architecture blueprint, there does not seem to be a standard definition in the field of enterprise architecture. Based on construction architecture, it can be assumed to be a diagram or set of diagrams describing core domains and their relationships. However, I have also seen that it can even be a code base for a template project. In my opinion, the architectural vision explains what you want to solve and how you want to solve it, and the architectural blueprint visualizes the solution at a slightly more detailed level. So both artifacts complement each other.
Is an architectural vision or architectural blueprint always necessary? No. If the scope is small and isolated, it is sufficient to identify only the design drivers.
What can architecture vision and blueprint contain?
An architecture vision is a collection of decisions that serve the business goals. It shows how decisions are based on the business architecture (values, vision and strategy) and the concerns of the stakeholders. The vision should remain at a high level while being concrete enough to act as a guideline for future decisions. For example, identifying the key non-functional requirements as design drivers, such as maintainable, security and usability, is a good start. The next steps are to make them measurable and make the first decisions on how to address them. The focus should be more on answering questions like WHAT and WHY rather than on HOW, which might be too detailed. The architecture vision should include a timeline up to which point the applications of the scope should follow the vision. According to TOFAG, it contains 0.1 version of the different domain architectures: business, data, application, technology. In other words, it can contain a bit of everything.
An architecture blueprint can show the relationship between the architecture domains (business, data, application, technology) and the design drivers and visualize them a one-pager, similar to a context diagram for an application. The software architecture canvas or Conceptual Blueprint could be used as examples for inspiration.
I am sometimes asked how much technology decisions should be included in the architectural vision. I think the more technological aspects that are added, the faster the artifact becomes obsolete. Therefore, I would keep the specific technology-related decisions to a minimum and focus on concepts such as the interaction between components or the security requirements.
One way of presenting the initial architecture decisions is to group them according to the ArchiMate framework:
Examples of the content of architectural artefacts
Here are a few concrete examples of the types of artifacts that an architecture vision and blueprint could produce as a result:
- What are the main components and how do they interact
- Brief explanation of the existing components and how they are used, for example how to use the permission management or auditing component. This can be a ready-to-use attachment for offers.
- Template of an architecture showing the mandatory, optional, existing components and where new applications can be created
- Which patterns are used
- Architecture principles related mainly to non-functional requirements
- Walking skeleton
- Used standards
- Checklists, How-Tos, decision-trees to support creation and review of an application architecture
What to consider when documenting the architecture vision and blueprint?
The main goal is to identify current and future concerns and link the documents to the existing business landscape. We have noticed that when the architectural documentation is not linked with the actual business cases, it is more difficult to understand and can therefore remain unused in the running projects. In that case, the artifacts themselves would have no value.
From our experience at ELCA in multiple enterprise architecture mandates, we start creating the architecture vision based on following aspect:
- by getting to know to the business branch
- by interviewing and leading workshops with the stakeholders
- by reading the possibly existing standards.
Architectural artifacts document mainly the architectural decisions and their background. In addition to the architectural decision itself, for example “Services need to follow the hexagonal architecture”, I find it useful to document also the considered alternatives, advantages and drawbacks. As the blueprint will last for years and may be challenged by new colleagues and peers asking the exemption for an application, decisions can be made more quickly, when the reasoning is already documented.
Remember that different stakeholders need a different level of detail and technical information. Ideally, everything is documented just once in a single tool and presented by different viewpoints, but in my experience, different formats are needed. For example, the detailed modelling is done in a modelling tool, architecture principles are in a format, which can easily be added as an attachment to a proposal and an overview is in confluence or in office-format for a quick introduction. It is a challenge to explain the technical requirements in a way that is understood by both technical and non-technical stakeholders, which is why the different documents need a different level of detail.
The length of the documentation or the number of viewpoints should be kept compact to ensure the readability of the artifacts.
Since the vision and blueprint are long-lasting artifacts, they will also change over time. There may also be applications that cannot adhere to the guidelines. For example, products are less customizable than individual development. Therefore, it is important to define a process for compliance:
- How to update the architecture vision and blueprint
- How to apply an exception to the architecture
The processes can include decisions about who reviews the change, who accepts it, and how it gets documented. This may sound time-consuming, but once you get used to the review routine, it may only take two emails. Without these processes, the architecture vision and blueprint can easily become outdated, and there may not be an overview of which projects deviate from the guidelines.
It is also important to consider how the architectural vision and design will affect the existing projects, not just the new projects. For example, do the existing projects need to be adapted, and if so, in what timeframe?
To summarize, here’s how to ensure effective usage of the artifacts:
1. Make them easy to use
- Keep it short, communicate where it is, use accessible tools familiar to the target group.
- Use different formats for different usages.
2. Support and verify the usage
- Provide guidance.
- Provide reviews.
3. Keep them up-to-date
- Update them when necessary.
- Allow justified exceptions.
Which challenges and risks could be faced?
In addition to the usual “not invented here” syndrome, resistance to change, and analysis paralysis, I think that the following aspects can be a challenge when introducing the architectural vision and blueprint:
- When there are many guidelines to follow, they may be too restrictive, difficult to understand, or easily outdated. To solve this issue, the focus should be on a few guiding principles. To keep the artifacts up-to-date, they should be reviewed regularly, for example, every six months or when a new project is started.
- If the decisions are not linked to the business architecture, they could end up being just a collection of cutting-edge technologies that may not be suitable for current projects or may become obsolete in a few years. It is important that the decisions are well justified and linked to actual business concerns.
- The guidelines might be too high-level or abstract, preventing the implementation team from making concrete decisions based on them. It is important not only to explain the vision at a high level but also to concretize it sufficiently.
If you want to learn more about creating an architecture vision, I recommend this article. It provides a deep dive into other aspects of the architecture vision and offers concrete steps for creating it.
Summary
The architectural vision and blueprint provide guidance for new projects and enable component reuse. To benefit from them, a link to the business architecture and a process for keeping them up-to-date are required. Remember that enterprise architecture is an ongoing process, so the architectural vision and design should be viewed as living documents.
