Architecture Principles: An approach to effective decision making in software architecture

Table of Contents

• What are Architecture Principles?
• What are the basic characteristics of good architecture principles?
• What are the pitfalls of creating architecture principles?
• Examples of real-world architecture principles
• Bonus: Continuous Architecture Principles to the rescue

What are Architecture Principles?

If we ask Eoin Woods (Author of the books, Continuous Architecture in Practice, and Software Architecture Metrics) what architecture principles are, he explains the architecture principle as follows:

A declarative statement made with the intention of guiding architectural design decisions in order to achieve one or more qualities of a system.

If we take a closer look at this definition, we find several interesting parts in this definition.

"[...] intention of guiding architectural design decisions [...]"

As a software architect or a team of software engineers, you have to deal with and decide on many architecture issues.

But how do you decide these questions? Gut feeling? :-)

That's is probably not the right approach.

As we learn from the Software Architecture Canvas, there are quality goals that are drivers of architecture.

Here Eoin refers to the quality goals with the part:

"[...] in order to achieve one or more qualities of a system."

But deriving quality goals to architectural decisions isn't always easy.

So this is where architecture principles come into play, serving as a beacon for architectural decision-making.

Architecture principles are very valuable when negotiating and communicating decisions with key stakeholders. If stakeholder or team members don't understand the whole derivation of an architectural decision, you can point to the specific architecture principle.

In your team or with your key stakeholder, you can have an effective dialog when principles are violated to highlight future problems.

Architecture principles are the most widely used type of guidelines for software architects.

What are the basic characteristics of good architecture principles?

An architecture principle should have the following properties that make it a good principle:

Comprehensible & clear

The principle should be reasonable, logical and consistent.

Architectural principles should be like marketing slogans.

Architectural principles should be like marketing slogans. They should be simple to understand and easy to remember for everyone involved.

Provides guidance

When you make a decision, you can easily use the principle as a guide. It brings efficiency to your decision-making process.

Testable

The principle should be verifiable, whether work is done according to the principle and where exceptions are made.

Atomic

The principle requires no further context or knowledge to be understood.

In summary, architectural principles should be written to enable teams to make decisions: they're clear, provide decision support, and are atomic.

What are the pitfalls of creating architecture principles?

What do you think about the following principle 👇?

"All software should be written in a scalable manner."

IMHO this is a bad example of an architecture principle.

What software engineer create software that is explicitly not scalable? None.

Architecture principles are too general and not verifiable

The above principle is too general and not verifiable. Nor does it provide guidance for a specific decision.

As you can see there are some traps you can fall into when dealing with architecture principles.

Architectural principles cover all contingencies

Another bad practice is to create a complete set of principles that covers all eventualities. This usually leads to a long list of principles that are written in great detail and usually require lengthy editing. Often, however, these principles aren't embedded in the thought process of the teams making the actual architectural decisions.

Ensure that there are only a small set of architecture principles.

Ensure that there are only a small set of architecture principles.

A small set is extremely valuable if the principles are fully embraced by a team and influence the decisions they make. Everyone in the product team should remember the established principles at all times and in their daily work!

Examples of real-world architecture principles

Let's discuss some architecture principles in my practise.

Example 1: "Use cloud services if being lock-in to a particular provider is acceptable."

If you use a cloud service, you're de facto tied to a specific provider. The use of managed services should therefore be chosen carefully.

That's why we've adopted in a product team the following architecture principle.

"Use cloud services if being lock-in to a particular cloud provider is acceptable."

Whether this vendor lock-in is acceptable depends on several criteria:

• The effort required to replace this managed service
• An acceptable lead time for providing alternatives.

Let's take a look at an example technological decision we had to make in the past:

We needed to evaluate a centralised identity and access management solution for our SaaS products.

In addition to meeting the functional requirements, we had two powerful IAM solutions on the shortlist:

• Keycloak (self-hosted)
• Auth0 (Managed, cloud service)

Following the defined principle of "Use cloud services if being lock-in to a particular cloud provider is acceptable." we have concluded that a centralised IAM system should be self-managed and not managed by a third-party provider because it's a huge effort to replace a managed IAM product and therefore there is no reasonable lead time to deploy an alternative.

In summary, vendor locking wasn't acceptable to us in this case. So this principle efficiently guides us to the right decision.

Example 2: "Prefer standard data formats over third-party and custom formats"

The next principle was about the selection of protocols for service communication.

"Prefer standard data formats over third-party and custom formats"

If you have multiple services that need to communicate with each other, the question of protocol and format arises.

In the protocol ecosystem there is a fairly new kid on the block: gRPC

gRPC (gRPC Remote Procedure Calls) is a cross-platform, open-source, high-performance protocol for remote procedure calls. gRPC was originally developed by Google to connect a large number of microservices.

So in our team, the question is: RESTful HTTP vs. gRPC?

The selection of a protocol thus depends heavily on the quality and change scenarios of the services involved.

But if you can meet the quality goals and underlying requirements with both options, like RESTful HTTP vs. gRPC, then consider yourself lucky to have such a principle.

This principle helped us choose RESTful HTTP over gRPC because RESTful HTTP is a widely accepted standard data format, while gRPC is more of a third-party format.

So here this principle speeds up our decision making, which doesn't mean that we don't rely on gRPC in certain cases.

Bonus: Continuous Architecture Principles to the rescue

In today's agile world, there is certainly less value in defining architectures up front, but our systems must still meet their demanding quality goals.

Stakeholders still have complex, conflicting, and overlapping needs.

There are many design tradeoffs to understand and make. More than ever, there are overarching concerns that must be addressed in order for a system to meet the needs of stakeholders.

Agile methodologies and DevOps techniques are fundamentally changing the way IT professionals, including software architects, work.

It's no longer a secret that architectural work is done by several people in a product team.

Architectural work is done in smaller increments and with a greater focus on early value creation than was often the case in the past.

Software architecture may be changing in the way it's practiced, but it's more important than ever.

Software architecture may be changing in the way it's practiced, but it's more important than ever.

You can discover a generation gap in todays software companies. Between the

• "Let's start building" (the agilist) and
• "Let's make a five-year plan" (the enterprise architect, program manager, project manager)

So let's close the gap between these orthogonal ways of thinking with the propagated six simple principles of "Continuous Architecture in Practise":

1. Architect products; evolve from projects to products.

Architecting products is more efficient than just designing point solutions for projects, and aligns the team with the customer.

This means:

• avoid big upfront architectural work
• do architectural work also in iterations
• focus in your architectural work on customer-facing product features with large architectural impact first
• plan 15 - 20% in every iteration for continuous architectural work and/or technical debt

2. Focus on quality attributes, not on functional requirements.

Quality goals determine your architecture!

Develop "walking skeletons" of the system or specific product features to find an appropriate architecture by programming and testing vertical and horizontal slices of the system to achieve specific quality goals.

The "walking skeleton" should be a business feature that is understood by the company's stakeholders.

3. Delay design decisions until they are absolutely necessary.

Design architectures based on facts, not assumptions. There is no point in developing and implementing capabilities that may never be used. It's a waste of time and resources.

Don't make decisions until the last responsible moment. Delay them until they're absolutely necessary.

4. Architect for change - leverage the "power of small".

Large monolithic, tightly coupled components are difficult to change. Instead, try to use small, loosely coupled software elements.

5. Architect for build, test, deploy and operate.

Most architectural techniques focus exclusively on building software. But an architect should also care about testing, deployment, and operations to support continuous delivery.

Tip: Take a look at the four key metrics.

6. Model the organization of your teams after the design of the system you are working on.

The way teams are organized influences the architecture and design of the systems they work on.

Why should we follow these principles?

The six principles of "Continuous Architecture in Practise" bring a new perspective to the overall process.

It doesn't only focus on the aspects of software design and development that most architectural approaches concentrate on.

This avoids the "big-architecture-up-front syndrome," where software developers wait and produce no software while the architecture team creates complicated artefacts describing complex technical capabilities and functions that may never be used.

These principles focus on the delivery of the software ("Working software over comprehensive documentation") rather than the documentation.

In this approach, software artefacts are considered as means of software architecture!

So use these principles along with your own defined principles to achieve effective teamwork in the discipline of software architecture.

Further Resources

Frontend Architecture Principles

If you take a look at specific frontend architecture principles, take a look at the following post.

Further thoughts