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.

What are the basic characteristics of good architecture principles?

Comprehensible & clear

Architectural principles should be like marketing slogans.

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."

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.

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