Every product needs an architecture vision

Most projects start with a plan. An architecture design on how the solutions should be built often comes from the initial offer estimate. As the details and implementations of the project come together, some aspects change and therefore the design changes. That's why most teams do agile development. Best case, this means also engineering diagrams and documentation are updated accordingly. Maybe even in architecture decision records.

Once the first phase of a project is over, the situation changes (this is often when the first budget runs out). Following a proper architecture and moving with thought becomes more difficult. An architecture vision can help with this circumstance.

What is an architecture vision

An architecture vision is a high-level idea of how the software should be built. It contains the main services as well as components of a system and describes their interactions. These include, in particular, areas that can only be changed at a high cost.

There are no hard guidelines as to how one should fabricate an architecture vision. More important is the fact that it forces development teams to reflect on where they want to go and think about the long run.

A simple generic example of an architecture vision

Next to a visual representation, the vision can include some paragraphs about general principles of the software. These are highly dependent on the situation of the product, the development team and the customers. These principles often touch on non-functional requirements like security, stability, maintainability or portability. Of course, the best case would be that all of these areas are developed perfectly, but there is usually not enough time to focus on everything.

For example, a team that builds a financial mobile application could decide that the correctness and security of the software are their top priority. Portability and performance could be less relevant.

Next to non-functional aspects of the software, technical decisions can be recorded in writing and made explicit. Like:

Each incoming request must be processed by the middleware
Database access only happens from component X inside the backend
We don't implement business logic inside the API adapters

How it can benefit the project

Except for the fact that it helps the whole team to think long-term and reflect, an architecture vision massively helps as a daily guideline. As requirements change and the roadmap gets updated, the tendency to start patching things together rises. Having guiding principles and a high-level vision is crucial for making better decisions. Each time a new feature gets developed, the intended implementation gets validated against the vision. This way implementations don't derail and limit future extensions.

Additionally, it's how the development team can incorporate innovative changes into the software. Thus keeping it in good shape and future-proof. The team can develop the product incrementally and keep architectural refactoring work to a minimum. With each sprint or feature the whole software solution gradually moves towards the vision. The development becomes sustainable.

How to create one

An architecture vision can be introduced to a project or product at any time. But particularly after the initial design is implemented it's crucial to discuss it. One can choose a whiteboard, sketching tools like Excalidraw. or others. There is no best tool to use to create an architecture vision. It is crucial for the architectural vision to be understood and supported by the team. Its form is of secondary importance.

The vision should:

Be lightweight
Define only critical aspects (less is more)
Be short
Does not need to clarify all questions
Provide guiding principles around non-functional requirements

Once the vision is created and accepted by the whole team, it should be prominently visible in the project documentation. Same as the software itself, it needs to be maintained and updated now and then. It can change dynamically as tech trends evolve, new patterns come into play and the software itself gets extended.

Incidentally, the efforts required to create the architectural vision do not increase linearly with the duration or size of the project. The reasonable effort to be invested is limited by the fact that one can only make stable statements for short periods.

In a nutshell, an architecture vision is an important prerequisite for targeted and sustainable development.

Best,
Flo