The Road to Clean Software Architecture

Olaf Thielke
4 min readNov 4, 2019

What is the secret to good software architecture?

What purpose does software serve? It allows developers to fashion bespoke systems that solve problems for its users. These ‘problems’ we call ‘business requirements’. To consider a software system successful, it must fulfil these requirements. This is WHAT a system does, the Business Logic.

On the other hand, there are the specifics of HOW the business requirements are met. These are the concrete details.

For example, consider the case of a customer paying for their shopping cart.

WHAT must happen

  1. Shopping cart must have something in it,
  2. Apply customer discount (if any),
  3. Add taxes to shopping cart total,
  4. Customer pays the shopping cart total.

Notice how none of these steps suggests that it’s a sale at an online store. It could be the description of a purchase at a supermarket or the local farmers market just the same. The reason is that the mechanics of an economic transaction are the same whatever the context — a buyer and seller transact goods or services for money.

OK, let’s look at the HOW.

Let’s assume the implementation will be an online store:


  • Native iOS Mobile app

Backend API:

  • ASP.NET WebApi 2
  • Database: MongoDB
  • Payment Gateway: Braintree

Which is more critical; WHAT our system does or HOW it does it?

WHAT the system does (here: pay for goods and services) is more stable, and more critical, than HOW it does it (iOS / WebApi2 / MongoDB / Braintree).

The HOW is more volatile — at some point, the business might want to support iOS and Android for their mobile app. Therefore we might decide to rewrite it in a hybrid framework like React Native. Or a web application is required as well. Or we find that MongoDB does not scale as well as we had thought and we want to replace it with a highly scalable database technology like Cassandra. Or swap the payment provider from Braintree to Stripe.

OK, but what does this have to do with architecture?

Well, we have just established that in a clean architecture, the Business Logic belongs square at the epicentre. As the WHAT component, it is crucial.

We have also determined that the details, the HOW, should be interchangeable. Developers wanting to replace one implementation of, say, the payment gateway with another, should be able to do this with ease. So, another desirable property of our architecture will be Pluggability. The pluggability ports, or plugs, should belong to the Business Logic — the implementation details are plugging into them.

For example, a SQL Server implementation of the database plugs into the Business Logic, not the other way round. Why? Because the Business Logic should remain ignorant of particular implementation specifics as otherwise pluggability would be lost. In other words, if the Business Logic has to be aware it’s connecting to SQL Server, then how are we meant to plug in MongoDB at a later point in time? It could be done by an enterprising developer, but it would be weird — using MongoDB but SQL Server artefacts. Best avoided. Keep ‘plugs’, or interfaces neutral and independent of any implementation specifics.

Furthermore, in an ideal architecture, the Business Logic could be hosted in different deployment media (web service, web app, desktop application, timed service, etc.) and packaged up and deployed from a simple single process ‘monolith’ to highly scalable microservice deployment model.


A great architecture acknowledges Business Logic’s central position. Business Logic is WHAT makes a system useful — its purpose. Each system fulfills the business requirements in different ways; maybe it’s a web app or a mobile one, perhaps it uses one database technology or another. Unlike the central business requirements, these implementation details, being more likely to change, should be pluggable. Pluggability provides options for architects and developers — they can change their minds later on.

Next Time

We’ll drill down further into an architectural approach called Clean Architecture.

If you enjoyed this article, please leave some claps — and a bunch of claps if you loved it! :) Thank you kindly.

Join my email list to fast-track your software engineering career.

When signing up, you’ll get my guide, ‘The Road to Master Progammer’, containing 3 powerful ideas to help you shorten your journey to expert programmer.