How To Enhance Your Software Architecture Design
Five questions and answers to improve your software architecture design
On August 10th, 1628, the Swedish warship Vasa set sail on its maiden voyage from Stockholm’s docks. However, just 1,300 meters into its journey, the ship encountered a light gust of wind that caused it to capsize, and water flooded through the gun portals. The ship quickly sank into the shallow waters of Stockholm harbor.
What happened?
When construction began in 1625, Vasa was designed to be the most advanced warship in the world. It was planned to be an impressive 70 meters long and equipped with a gun deck holding 64 bronze cannons, with a capacity for 300 soldiers.
Not only was the ship designed to be highly functional, but it was also meant to be a work of art featuring elaborate decorations and grandeur in its appearance.
The story of Vasa began when King Gustav of Sweden commissioned the construction of four new warships within four years. However, in the months following the order, the King made numerous changes to the ships’ specifications, which led to confusion and chaos among the builders.
The constant changes in design made it difficult for the builders to keep up with the King’s expectations, resulting in delays and frustration in the shipbuilding process.
On September 10th, 1625, disaster struck the Swedish navy, losing ten ships in battle. In response to the loss, the King ordered the builders to speed up the construction of two of the four ships he had commissioned.
A few months later, the King received news that the Danish were constructing a ship with two gun decks, prompting him to change the specifications again. The King instructed the builders to modify the design to include two gun decks instead of one.
The frequent changes to the specifications and the rushed construction process had a detrimental impact on the ship's stability. The addition of the second gun deck, along with the weight of the bronze cannons, raised the ship's center of gravity, making it unstable.
The original plans for the ship’s hull dimensions did not account for the added weight and the second gun deck, leading to structural issues. The builders were under immense time pressure to meet the King’s changing demands, which likely contributed to the inadequate planning and design flaws. These factors eventually led to the tragic sinking of the Vasa on its maiden voyage.
In summary, the Vasa warship sank because of:
- Unreasonable time pressure
- Changing specifications and lack of documentation or project plan
- Overengineering and innovation
- Lack of scientific methods and reasoning
Sound familiar?
It’s likely that if you’ve been working in IT for a couple of years, you’ve encountered projects that share some similarities with Vasa’s building process. Rushed schedules, unclear requirements, and poor planning can result in design flaws and functional issues, ultimately leading to project failure.
However, a well-designed architecture and architecture process can help prevent these risks and ensure the success of the project. Let's look at what is necessary to introduce such a process.
What Is Architecture?
Before we look at the five questions and answers, we have to define what we mean by architecture. Let's look at a couple of definitions.
“Architecture is the fundamental organization of a system embodied in its components their relationships to each other and the environment and the principles guiding its design and evolution.” — IEEE 1471 (2000)
“Architecture represents the significant design decisions that shape a system, where significant is measured by the cost of change.” — Grady Booch
“Architecture is about the important stuff. Whatever that is.” — Ralph Johnson
I really like the definition of IEEE because it defines all the aspects of what I think should be part of an architecture. I made these bold.
What type of architecture are we talking about in this article?
There are different types of architecture — for example, enterprise architecture, project architecture, business architecture, and information architecture.
This article talks about designing a software system and its cohesion with other applications and information systems. We call this software architecture.
1. Agile, Architecture, or Both?
Currently, most development teams use an agile development method. They work iteratively and take small steps forwards. Of course, this has many advantages. You let your software grow organically using agile teams. You don’t need a large staff that create designs in their ivory tower. It sounds very appealing.
And it is. But there is a downside. How do we handle planning? Didn’t we use the reference architecture to confirm if a project is moving in the right direction? Didn’t we use designs to let software developers implement the software correctly?
Development using architecture and designs has its advantages, so does agile development. But do we have to choose one or the other?
I don’t think so. It is about making clear decisions and still allow room for flexibility.
Instead of creating a complete software architecture design at the start of a project, you describe an architectural vision.
Architectural vision
You align this architectural vision with the business goals and strategic objectives. It describes the technical direction using guidelines while keeping in mind constraints such as scope and budget. Preferable you construct this architectural vision in cooperation with multiple development teams.
The architectural vision is then used for all the development projects in an organization.
Having an architectural vision enables you to use an architectural process that is more aligned to agile during the project.
This architectural process should have the following characteristics.
- Making only those architectural design decisions needed to implement the first set of user stories with the highest priority. This is based on the lean development principle called “The Last Responsible Moment.” Mary and Tom Poppendieck describe it in Lean Software Development: An Agile Toolkit as:
“Concurrent software development means starting developing when only partial requirements are known and developing in short iterations that provide the feedback that causes the system to emerge. Concurrent development makes it possible to delay commitment until the last responsible moment, that is, the moment at which failing to make a decision eliminates an important alternative. If commitments are delayed beyond the last responsible moment, then decisions are made by default, which is generally not a good approach to making decisions.”
- Creating vertical slices or spikes to prove and validate architectural design decisions. The spike should always deliver a working product that the development team can demonstrate.
- Not being afraid to change or optimize existing architectural decisions during development. The architecture should evolve during the development.
- Making architecture a team effort. The team should make the design decisions. Design ideas should evolve from the team by combing through the product backlog together.
The project architecture, which will result from this agile architecture process, should still fit within the organization's architectural vision.
2. Which Requirements Do We Use?
When you develop software, you base it on requirements. These requirements can be in any form, such as user stories or use cases. Software development mostly deals with functional requirements. If the user presses this button, then this should happen.
If you look at the architecture of a system, it is also based on requirements. But these are different requirements. For example, they describe how fast a system should generate a response. Or how many concurrent users should the system be able to handle?
You call these types of requirements non-functional requirements. The problem is, these non-functional requirements are often implicit.
But before making any architecture design decision, you have to make these requirements explicit.
Most teams don’t make the non-functionals explicit because they are hard to identify and even harder to measure. Luckily for us, there are several standards that you can use.
Don’t let the ISO qualification scare you. Use these lists as an inspiration to talk to your stakeholders. Ask them what the most important non-functionals for the new system are.
Or organize a workshop. Invite your stakeholders, explain non-functional requirements and why they are important. Let the stakeholders vote on the most important non-functionals of the system. For example, using dot-voting.
3. What To Do With the Non-Functional Requirements?
Now that you know which non-functional requirements are the most important, we are ready to start making design decisions. But this results in the following question: How do you translate the non-functionals into a software architecture?
By using patterns.
A design or architectural pattern expresses a relation between a problem and a solution. Although we like to think that our problems are unique, they are not.
For example, if the stakeholder values maintainability, you could use the layer pattern to separate several parts of the application. If performance is important, maybe layering is not the best solution.
You can search through catalogs of patterns for a solution to your problem. You can find catalogs in books or online, for example.
- Pattern-Oriented Software Architecture Volume 1: A System of Patterns by Frank Buschmann
- Design Patterns: Elements of Reusable Object-Oriented Software by Erich Gamma
- Patterns of Enterprise Application Architecture by Martin Fowler
- Clean Architecture: A Craftsman’s Guide to Software Structure and Design by Robert Martin
- The Open Group Architecture patterns
- Architectural patterns on Wikipedia
All of these references contain a catalog of patterns. Each pattern describes the problem it solves and in which context to use it.
4. How To Document the Architecture?
Once you have an architectural design decision, it is important to document it. You want to be able to communicate it to other developers.
It does not matter how you document the architecture. Communication is key. You could add diagrams to please visually oriented people. Currently I see many people using the C4 model for visualizing software architecture. I really like the simplicity of C4.
On the other hand, I am not fond of using UML as it lets you fall into the trap of documenting in too much detail.
As I said before, it does not really matter. Use Draw.io, Visio, or Paint. It is all about communication.
However, one crucial aspect is to document the reasons behind the design decision. You should document them rigorously and consistently. For example, “the end-user wants it” isn’t useful documentation of the rationale.
Instead, the explanations should include information explaining the context and reasoning. If possible, document the tradeoffs, criteria, and decision-making that led to selecting a particular design.
A good way to document the rationale is by using an architectural decision record (ADR). This is a document that captures an important architectural decision along with its consequences. Several templates exist for documenting ADRs.
5. How To Validate the Architecture?
To ensure that the architecture we are creating is aligned with the business goals and strategic objectives, we continuously must validate the architecture.
The reasons to perform an architecture assessment are the following:
- Problems found early in the software lifecycle are easier to correct.
- Refinement of architecture into an implementation preserves the qualities necessary for the final product to achieve those qualities.
- You cannot append software quality late in a project.
This architecture assessment process can be formal or informal and planned or unplanned. You could let the development team itself do the assessment or choose an external reviewer, preferably one who has no interest in the evaluation outcome.
If you do a review, you should be open to the topic and the people involved. You should be as objective as possible. Any hint of prejudice will certainly undermine your work. Jumping to conclusions is a deadly sin.
A simple review process could look like this.
First, you have to observe and discuss your observations. Observations that are shared between the specialists become facts. When the specialists disagree, the observations become opinions.
Secondly, establish your findings and discuss them too with other specialists. Findings may have a taste of your own opinion but should at least be defendable.
Third, draw your conclusions and report your recommendations to the team or team principal.
There are various formal methods to perform an architecture assessment, for example:
Although these methods are quite extensive, nothing prevents you from using only a part of them. Use them for inspiration and guidance.
Conclusion
This article discussed five questions and answers related to software architecture design.
Using an architectural vision, we saw how to combine agile software development and architecture. Then we looked at how to translate non-functional requirements into architectural design decisions using patterns.
We discussed that documenting the rationale of design decisions is valuable if done correctly. These decisions should include information that explains the context, reasoning, and tradeoffs. Architectural decision records are a great way to document them.
Finally, we looked at architecture assessments as a continuous process to validate your architecture.
This article should guide you in improving your current software architecture design and process. Ultimately, it will help prevent situations like the one we saw with the warship Vasa.
Thank you for reading, and always remember to continue learning!
