Clean Architecture - The Simplest Explanation

Clean Architecture - The Simplest Explanation

10 January 2024

"No way this is Architecture!"

My mind was rejecting the idea of Clean Architecture as I was learning it.

It was 2010, and architecture meant cloud platforms, web servers, databases, load balancers and reverse proxies, right?

I had been thinking in terms of Systems and Solution Architectures.

Software Architecture had slipped under my radar.

Until that fateful day, when I learned about Clean Architecture (CA) from an Uncle Bob video.

Of course, I knew programs should be well-structured for maintainability.

I had yet to learn how differently.

What is Clean Architecture?

An revolutionary approach for designing highly maintainable, pluggable software systems—that is Clean Architecture.

As such it is extremely useful when building complex, yet robust software systems where we need flexibility to make significant modifications.

Today I will explain the essence of Clean Architecture in the simplest way.

Let's go!

An Example

Say we are writing an e-commerce web app. In particular, we're developing the payment workflow at checkout.

After gathering the requirements, we'd be wise to start designing the checkout process before writing code.

One way to kick off our design would be by starting with the database, outlining the needed tables, columns, keys and indexes.

But that would be a mistake.

The Clean Architecture design process differs from a database-centric approach.


Clean Architecture asks us to identify Business Logic first.


CA recognises the priority of Business Logic.

Business Logic is the most important part.

Business Logic

What is Business Logic [1]?

Business Logic represents the program's behaviour independent of technologies like web and database.

It's the purpose of the software; i.e. what it's trying to achieve.

For our e-commerce web app, when the customer pays for an order at checkout, business logic is the payment workflow—the individual steps that contribute towards a successful order payment process:

  1. Pay for the order
  2. Record order as paid
  3. Inform customer of successful payment
  4. Dispatch order

None of these steps mentions a MongoDB database, AWS, or even a specific payment gateway, like PayPal.

Business Logic is concerned with high-level business policy and processes, not technology details.

So, we could encapsulate the high-level business logic of paying for an order in an OrderPaymentWorkflow class [2]:

OrderPaymentWorkflow class

Technologies & Mechanisms

High-level business logic workflows are required, but we also need specific mechanisms to achieve the business logic objectives.

In other words, we need databases, the web, cloud platforms, and other technologies to do the work.

We must have a payment gateway, like PayPal or Stripe, for the customer to pay for their checkout order.

Clean Architecture isolates technological mechanisms via the Business Logic Boundary.

This BL Boundary consists of abstractions, like interfaces.

Let's choose IPaymentGateway as the interface into which specific payment gateways (PayPal, Stripe, etc.) will be plugged into:

IPaymentGateway interface

The black arrows represent a call and its return.

Let's assume we choose PayPal and decide to use their published Software Development Kit (SDK).

So far, so good.

Yet, how does OrderPaymentWorkflow use the PayPal SDK via the IPaymentGateway interface?

Let's keep in mind, the PayPal SDK does not know how we want to call it.

PayPal SDK

Something's still missing.

We need another component that bridges the gap, the PaypalPaymentGateway:


The PaypalPaymentGateway has 3 responsibilities:

  1. It implements the IPaymentGateway interface, and
  2. internally converts the call coming from the workflow to calls into the PayPal SDK, which
  3. returns the responses from the SDK into responses appropriate for the workflow.

The PaypalPaymentGateway provides the adapter—or plug—between the business logic and the specific technologic mechanism, the PayPal SDK.

Why design it like this?

One clear advantage: This design is pluggable. If we want to switch out PayPal and replace it with Stripe, we could reference the Stripe SDK and write a StripePaymentGateway which plugs into the Business Logic via the IPaymentGateway.


There is more detail to Clean Architecture. Yet, this to-the-point example explains the core concept of achieving business logic independent from the technology mechanisms.

To recap:

Clean Architecture allows us to create modular, pluggable systems, where it's easy to replace one specific implementation with another. And that's why Clean Architecture[3] is so useful and such a big deal.

And why it's crucial to know and understand CA as a modern software engineer!

  1. Often also called the Domain, as in Business Domain.
  2. I prefer the suffix UseCase better than Workflow as it more precisely expresses the business logic nature, a use case. We can have workflows other than business logic ones (e.g. data workflows).
  3. Other architectures, like the Onion or Hexagonal, have the same idea at their heart.


← Back to home