Evidence, criteria, agreement, documentation, realization/review

It is good to know when the most responsible moment for an architectural decision about a pattern or technology has come. But when can a decision be considered done? This post suggests five criteria to help you decide whether you are ready to move on.

Photo by Massimo Sartirana on Unsplash

The proposal is inspired by the five SMART criteria used in project and people management (but also when eliciting non-functional quality requirements). Let’s look at them one at a time.

You have gained reason to believe that the chosen design (selected pattern, technology, product or open source asset and its configuration, that is) will work…

This post proposes five principles for API design, summarized as POINT: purposeful, style-oriented, isolated, channel-neutral and T-shaped.

Context: Web API Design and Evolution (WADE)

Application Programming Interfaces (APIs) have been around for a long time, both local ones inside modular programs and remote APIs connecting operating system processes and distributed systems. Message-based protocols such as RESTful HTTP, gRPC and GraphQL dominate the remote API realm.

IMHO, any API, whether local or remote, should address an actual client information or integration need. When delivering related functionality, three types of quality attributes are particularly relevant:

  • Developmental qualities. APIs should be straightforward to learn and easily consumable for developers and…

In Part 1 of this story, we went from architectural decisions to more general software design decisions. In this Part 2, we will move on to strategy decisions and then, becoming even more exploratory, any (or arbitrary) decisions.

Strategic Decisions

Let’s investigate cloud strategy as an example domain.

Gregor Hohpe, of “Enterprise Integration Patterns” fame and now providing IT strategy and cloud transformation advice, emphasizes the importance of decisions and decision making for architects, but adopts business-level decision option theory. Decisions stay with him as he takes “The Software Architect Elevator” from engine room to penthouse:

  • ADs and their rationale make a…

Decision Making: Weighting Options to Solve Complex Design Issues

If architectural decision records are so useful to capture software design rationale, why not extend their scope? This is Part 1 of a two-part story; Part 2 goes from software design decision to strategic ones and any decision.

Architectural Significance and Decision Making Criteria

In “Architectural Decisions — The Making Of”, I motivated why Architectural Decision Records (ADRs) are such an important software architecture artifact and featured a few templates, including Y-Statements (my own creation). Let’s take a step back and carve out what makes a decision architectural, and then discuss whether the ADR templates are general enough to capture other types of decisions as well.

Service-Oriented Analysis and Design with DDD and MDSL (Source: [1])

This post shows how to advance from a set of user stories to OpenAPI specifications to API provider stubs via strategic and tactic DDD. This seven-step journey is partially supported and automated in two open source tools, Context Mapper and Microservice Domain-Specific Language (MDSL) Tools. Background information is available here and here.

Prerequisites: The instructions below assume that you have Context Mapper Version 6 and MDSL Tools Version 5 installed.

Step 1: Elicit Functional Requirement(s)

Write a user story in the Context Mapper DSL (CML), as explained in the Context Mapper documentation:

UserStory PaperArchiving {
As a "Researcher"
I want to create…

My Frequently Accessed Venues (FAVs)

This post points you at valuable templates for documenting software architectures as well as a pattern languages that can support their creation.

Architecture Description Formats

When it comes to documenting software architecture requirements and designs, some of my most frequently visited resources are:

  1. The twelve-section arc42 template “takes the pain out of documentation” and is accompanied by many hints.
  2. ISO/IEC/IEE 42010:2011, defining what frameworks are and making the case for capturing decision rationale. There is a template to ease the creation of 42010-compliant architecture descriptions[1].
  3. OpenUP seems to have lost weight in recent years[2]. But it still is a good place to look…

The Software Engineering Alphabet

Aspect-Oriented Programming (AOP), Behavior-Driven Development (BDD), CDD, DDD, EDA… can we cook some more “method and practice soup”?

Story 22 on “Diagram-Driven Design” in Gregor Hohpe’s “Software Architect Elevator” reminded me that I was one of the pundits that once contributed to an “A-Z list of 26 new development strategies” .

This post is a little more conservative and reminds us of actually existing ones.

Some “driven” methods and styles (past and present) are:¹

A Collection of “Mighty” Method Elements on GitHub

Real-World Architecture Metaphor: Repositories, Artifacts/Building Blocks, Patterns, Architectural Style(s)

The Design Practice Repository (DPR) on GitHub compiles proven method elements and other knowledge nuggets for API and (micro-)service design — and more general software architecture work.

Update (May 21, 2021): The DPR content also comes as an ebook now. The current draft (80% complete) is available on Leanpub.

Update (December 8, 2020): Story splitting and CRC cards now featured, tutorial enhanced with architecture decision record(s), many elements edited and additional background information provided.

Methods: The Good, The Bad and The Why

Read on if you agree:

We all learn well from mistakes — but do these mistakes have to be our own?

You might be thinking that…

Business value/risk, stakeholder concern, quality level, external dependencies, cross-cutting, first-of-a-kind, past troublemaker?

What is important when analyzing and designing software architectures, and what is not? This post proposes 5+2 criteria for the architectural significance of requirements (and other artifacts) and applies them to several examples.


Let’s assume it is the first day for you on a project that has been running for a while (for instance, one that modernizes some legacy system); you might be an external consultant that has just been hired, or have switched role and project internally. What to work on first?

As a software engineer with architecture responsibilities, I would like to prioritize technical issues quickly so…

Three positions and evidence for one of them

Microservice architectures evolved from previous incarnations of Service-Oriented Architectures (SOAs) to promote agility and elasticity. They are often visualized with hexagons and onions (to emphasize service autonomy):

I see such microservices (defined by seven tenets here) as a contemporary implementation approach for Service-Oriented Architecture (SOA) principles and patterns, emphasizing and benefiting from modern software engineering practices such as domain-driven design, containerization and DevOps.

Please read on if you would like to learn why — or disagree.

Three rather different positions can be observed, both online and in print:

  1. Microservices as a new architectural style competing with SOA and to be…

Doc SoC

Domain-Driven Designer, Architectural Decision Maker, Serviceorienteer

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store