Architectural Mechanisms

Architecture is a high level view of a system in the context of its environment, dependencies and technology. Architecture describes structure, behavior, integration and aesthetics.

Architecture must be solid, useful and beautiful.

In HSD the Architecture View encompasses Enterprise, Solution and System Architecture.

Architectural Mechanisms are small parts of an architecture that address a specific important concern, provide a common way of doing something or are a good example of how the architecture behaves and is structured. Architectural Mechanisms are described in terms of structure and behavior.

Mechanisms explain how the architecture does something. Mechanisms exist within the context of an architecture which provides overall structure so we recommend mechanisms are tightly bound with an Architectural Overview and are only used to refine the architectural description, where necessary, as indicated by the Architectural Profile. Architectural Mechanisms take different forms in Enterprise, Solution and System Architecture.

In Enterprise Architecture, the mechanisms are focused on technical standards, decisions, environments and ways of working.

In Solution Architecture, mechanisms are focused on integration, communication, distribution and cross-product concerns, especially non-functional.

Both are discussed in more detail in the  Enterpise Architecture and Solution Architecture articles. This article, focusses more on System Architecture mechanisms.

There are three main sources for finding mechanisms: the requirements, the architectural profile and the team. Primary differentiating functional requirements (especially Integration Scenarios) are often good candidates for explanation with a mechanism as are significant non-functional requirements such as persistency, audit logging, authentication, localization etc. Teams of developers will often seek common ways of approaching a problem in a system to avoid duplication and increased quality risks. Finding a common way of doing something (such as communicating between different parts of a large architecture) improves code consistency, maintainability and quality. These “common ways” are best described as mechanisms.

Mechanisms exist to explain the architecture, elaborating too many mechanisms, or writing too much to explain a mechanism, can actually inhibit that communication. Often working examples make for better explanations than models. Having “just enough” mechanisms to effectively describe the architecture, and not so many that teams are stuck designing instead of developing code is a difficult balance to strike. – as discussed in the architecture view. Finding the right balancing point between explaining enough to speed things up, but not so much as to slow things down, is where a talented Architect really shines.

Mechanisms are best expressed in terms of their structure and behavior. To describe structure a simple class diagram is often useful although we don’t tend to worry too much about the rules of UML, or other modeling languages, so we’ll frequently mix in some other symbology, rich graphics or color coding. In terms of behavior, traditional UML modeling would suggest the use of a sequence diagram or collaboration diagram, and these might be useful if the team understand these formats, but often a simple activity or state diagram can be more useful. A useful technique in user facing layers is to create activity diagrams with GUI mockups as the nodes in the diagram or User Experience storyboards.

Regardless of the format used, we recommend limiting description and documentation to the minimum necessary to communicate clearly. Just because one flow is worth explaining doesn’t mean all related or alternate flows in a mechanism require a description. Instead we recommend architectural specification by example, one or two flows serve as an example for the mechanism as a whole. Note that a code (or pseudo-code) snippet can be an excellent explanation of a mechanism, visual models are not always necessary. The explanation needs to be simpler than the implementation otherwise it is wasteful.

The most useful mechanisms can be downloaded, integrated into your code and executed.

Here’s an anonymized example of a persistency mechanism for a system (that was also used in the Architectural Overview example):

The words in this example aren’t important, and they’re deliberately not all readable on this graphic, they are there to give an indication of what kind of content we find useful.
We recommend that a mechanism has a simple name and a short description that describes the mechanisms significant flows. We also (in the top left) have a list titled “Appropriate for Stories like:” which lists a number of requirements which indicate the kinds of areas of the system where this mechanism might apply rather than a hard traceability link and an exhaustive list. If there aren’t any requirements in this list, then maybe the mechanism shouldn’t exist.
There’s some short explanatory text that describes in a bit of detail what the mechanism is for, and what problems it’s solving.
We then include a structural diagram on the left and in this case a UML “sequence diagram” explaining a significant flow with some textual content below. Although our examples have been created using a modeling tool, photos of explanations on a whiteboard are just as suitable.
If you’re not familiar with modeling standards you can safely ignore this paragraph! Those with a background in UML will notice that we use the “parameterized collaboration” icon to house the mechanism name, because the mechanism is a contained realization of part of the architecture. We also use a VOPC-like structural diagram elaborated through a number of behavioral flows. In this sense our lightweight mechanism has all of the traditional mechanism features. However, we’ve broken a number of UML rules in the structural diagram and the end result is a composite artifact with explanatory text.
And, we’re back! Although we’ve used some standard UML symbology and fragments of diagrams in our mechanism example we do not recommend slavishly following this standard for all mechanisms. Many mechanisms are better explained by example rather than specification.
The following is a real mechanism regarding creating a new plugin for a plug and play processing architecture.
This mechanism has the same introduction elements, a name, short description and an indicator of which requirements the mechanism is related to. There’s even a small little class diagram as part of the introduction text.
The rest of the mechanism is explained in some configuration steps, code snippets and a full code example. There’s even a link to download the code from a code repository. This mechanism has been used about 50 times in a particular project and is rated the most useful by the development team. The point of this mechanism is not how clever the plugin design is, but how to use it.

The Flip Side

Just as requirements are often best described in terms of the tests that quantify them, mechanisms can also have acceptance criteria or test ideas associated. In Holistic Software Development we like to place these criteria on the flip side of the mechanism (if it’s in physical form).

Although many are easy to frame in terms of customer acceptance tests (e.g. Search Mechanism will have performance, consistency and accuracy acceptance criteria) some are a little harder to frame.

Technical mechanisms formed to provide a common way of doing something in an architecture or to express the shape and aesthetics of an architecture may feel like they only make sense in terms of the development team’s acceptance criteria, however we recommend ensuring that these mechanisms relate back to a requirement somewhere, otherwise this could be an indication of unnecessary gold-plating.

Architectural Context

Architectural Mechanisms may be used to explain parts of System Architecture, Solution Architecture or Enterprise Architecture. The difference in these contexts can be in two ways:

  • Usage
  • Conceptual level

When considering usage, the difference is only a matter of how widespread use of a mechanism is from a system, system of systems, or organizational perspective respectively.

In terms of conceptual level, mechanisms are often be described differently at Solution level as system internals won’t be visible. However, in terms of interaction between interfaces and code-examples for integration the same formats as used for System Architecture Mechanisms can be useful. Enterprise architecture will often focus more on standards, technologies, platforms etc. and so be less concerned with specific requirements.

In our experience there will be a mix of “design-based” mechanisms vs. “standards-based” mechanisms. At a System level the balance tends heavily towards design-based. At an Enterprise level the balance is heavily towards standards-based. Solution architectures tend to be around 75% design based. Obviously these indications are gross generalizations rather than guidelines or targets.

A healthy team/organization will accept challenges to established mechanisms as new ways of solving problems or new technologies emerge. However, changing accepted Solution or Enterprise mechanisms in line with each technology fashion or disruption creates an unnecessary wasteful architectural churn for product development and should be avoided.

Changing common architectural mechanisms must be considered from a cost/benefit perspective and so we recommend that for the Enterprise or long running Programmes such a change is managed via a Portfolio Request. Avoid too many common mechanisms at an Enterprise or Solution level, especially if they cause inter-dependencies, cause architectural fragility and create an impedance to progress resulting in a lack of business agility. We recommend that mechanisms are atomic and isolated. A team should be able to use a Solution or Enterprise mechanism without having to adopt them all. Conversely, not updating architectural mechanisms over time creates technical debt and can cause significant performance, security and other non-functional problems.

Any system level mechanism may be a candidate for adoption at Solution or Enterprise level. If a system is being developed in the context of an Enterprise or Solution architecture, then it should use existing mechanisms or have a strong technical/cost/benefit justification for not using them. Multiple mechanisms for the same problem in an architecture cause significant supportability problems.

Mechanisms can often be implemented using existing technologies, frameworks or open-source libraries (e.g. Apache Camel for routing and mediation rules). Such frameworks, packages and technologies will often add a little more than strictly required by a project since they overlap at the conceptual edges with each other –  introducing architectural bloat and confusion. We recommend using an existing technology where the solution is close to perfect, not where the requirements need massaging to fit a technology. If selected technologies need disambiguating, there is a problem in the clarity of the architecture. Avoid picking up a framework to implement a simple mechanism just because it’s interesting or new.

Architectural mechanisms chunk up the architecture into separate parts. As such they can be delivered incrementally, enabling iterative and continuous delivery.