When Is Architectural Work Justified

What do we mean by a software architecture? To me the term architecture conveys a notion of the core elements of the system, the pieces that are difficult to change. A foundation on which the rest must be built.

Architectural work and a certain amount of planning is justified in all those areas in which many risks and unknown factors are to be expected and which - as the quote from Martin Fowler illustrates - are difficult to change later on.

Important architectural decisions are those that might endanger central project conditions: budget, schedule or product quality. Rigid designs or too early decisions are unnecessary for topics that can easily be changed later or carry only minor risks. It is therefore advisable to prioritize architectural work on the basis of risk.

High risks typically arise, for example, from

  • Difficult integrations
  • The use of new, unknown technologies
  • Very high qualitative requirements, for example in terms of performance or availability
  • Unclear responsibilities or a high degree of organisational dependencies

If architectural work is not approached in a structured way, there is a risk that fundamental non-functional requirements cannot be met. In the worst case, this is noticed late in the project and can't be changed anymore. For example, an acceptable performance level may no longer be possible without rebuilding large parts of the solution. Also, maintainability will most likely suffer, and missing architecture documentation will make it difficult for new team members to familiarize themselves with the structure of the software.

Starting With The Architecture Vision

Creating an initial architecture vision together with stakeholders and the development team is a lean way to work out a common direction. This without decisions being made unnecessarily early, thus keeping the learning window open for as long as possible. The architectural vision should include the following key points:

  • Key requirements and objectives
  • System context and interfaces to the environment
  • Most important quality requirements (prioritized)
  • Functional and technical risks

Over time, the following points can be added to the architecture vision as they become more solid:

  • Architectural principles
  • technology stack
  • Rough outline and domain model

Iterative Architectural Work

We recommend separating architectural work from the implementation and scheduling it in the product backlog:

  • Feature-specific design efforts as acceptance criteria on the User Story
  • Large architecture decisions and efforts as a quality story in its own right (e.g. redundancy)
  • As checks in the Definition of Done or architectural guidelines
This means that architectural work and decisions find their place in agile procedures - transparently, prioritized, risk-driven and iterative. The architectural vision provides the guidelines and foundations to be able to make consistent decisions. In contrast to classical approaches, where architecture work was often understood as design work at the beginning of the project. The learning curve and changing requirements were thus difficult to take into account. later on

Architecture Roles

How the architecture work is distributed in the team and thus which architecture roles are necessary and is dependent on the existing architectural factors: Is the system distributed and complex, or is it a simple forms application? Are new technologies required or are complex interfaces to be connected? Are there very high quality requirements in an area, for example performance or flexibility? Depending on these factors and the experience available in the team, one of the following role models is conceivable:

  • No named architect: Architectural work is distributed within the team in a self-responsible manner
  • Architecture agents: These are typically experienced team members with architectural expertise who support the team in their architectural work.
  • Architect as coach: The team plans architectural work on its own responsibility, and is supported by an expert architect where necessary.
  • Classic architect role: The responsibility for the architecture lies with one or more persons, who perform the role of the software architect. Ideally in close cooperation with the team, to ensure a short feedback loop.

Architecture Documentation

When using agile methods, the question of documentation often arises. An architecture documentation is always required from our point of view, whereby the work to be invested in it depends on the complexity of the system. The most important elements of such a documentation are

  • architectural vision, most important cornerstones
  • context view, what are the interfaces
  • Quality requirements: Which non-functional aspects are important, if possible backed up with concrete figures?
  • architectural decisions: Why was the system built that way - the how can usually be read from the code

It is not recommende to document detailed implementation aspects of the system, which can be read from the code and are subject to frequent changes. These are typically not relevant to architecture.

It is important to consider who the stakeholders consuming the documentation are. One of the most important stakeholder is the new project team member, who should be able to quickly gain an overview of the system and its requirements and goals.

The form of documentation should be easily accessible and editable: collaborative systems like Confluence are well suited, for example. What also works well are approaches in which the documentation is directly stored in the version control system together with the source code, e.g. as Markdown or Asciidoc. We have also seen good results in customer projects using Structurizr, a tool which allows to describe the documentation as code and create views from it.

Interested?

We would be happy to support you taking an active approach towards software architecture when using agile methodologies: Our contact details