Introduction to clean architecture: Part 1

If you ever walk through the kitchen appliances section of a shopping mall, you will see lemon juicers made of steel, plastic and wood. The raw material doesn’t matter. One glance at the simple tool and you know what it is. The details about what the juicer is made of, who made it and how the holes at the bottom were poked become irrelevant.

Similarly, if you look at a temple, you know that it is a temple. A shopping mall screams at you to come shop inside. Army enclaves have tell-tale layouts, stern looking guards and enough signboards to let you know that you should stay away and avoid trespassing.

Meanwhile in software…

That’s not true with software. Pick up the source code of any application in the world today. If you are a programmer, a look at the arrangement of directories tells you what tool was used to build it. ‘Oh this is NodeJS Express’, ‘Well, well, this is Ruby on Rails’, ‘Hey, this programmer uses Python and Flask, just like I do. Hi five!’. Sentences like these are very common in the world of software. However, let’s stop these programmers and ask them. ‘Nice, but what does this program do?’. They stop in their tracks and then pepper you with jargon. ‘Uh, for that I’d have to go into the app directory and look at the contents of the view, model and controller sub-directories. Give me 30 minutes, I will figure out.’ ‘Let us run the program and we’ll find out!’

How that sounds

Let’s go back to the appliances and buildings and try the sentences of the software professionals. ‘It’s a building made of brick and glass, but I can’t tell you what it is until I go in and find out.’ ‘It’s a tool made of wood. Let’s try to put different things inside it, fiddle with it and find out what it does.’

Clearly, that’s not how the real world works. Why should software be any different?

It doesn’t matter who built this structure, where it is built or how it was built. It screams out ‘SOUTH INDIAN HINDU TEMPLE’

What is clean architecture?

Clean architecture is a way of developing software, such that just by looking at the source code of a program, you (or your programming team) should be able to tell what the program does. The programming language, hardware and the software libraries used to achieve the objective of the program should become irrelevant. The aim of clean architecture is to make the following sentence possible: ‘Hey, the arrangement of directories tells me this is a shopping cart app. I don’t know which programming language or software library is used. I need to go into the directories and find out.’

More than being a method of writing software code, clean architecture is a way of thinking. It is a way of designing things such that the ‘what it is and what is it’s purpose’ become more important that ‘how it is made’. While software is an excellent candidate for applying clean architecture, I can think of zillions of other places where the purpose is hidden so deep and the method is so visible, that the you can lose patience trying to find out. Here are some: Non-disclosure agreements and lawyer speak, financial instruments, government circulars and tenders. These things are terribly deprived of the clarity that clean architecture can help them with.

Clean architecture was first introduced to the world by Robert Martin, a software engineer with over 25 years of experience.

What does clean architecture achieve?

Here is the list of things that applying clean architecture can make possible for you.

The purpose stands out and the details get buried

The purpose of an eCommerce system is to help the customer buy goods and services, while the vendor gets to earn money. This is achieved by five chief operations.

  1. Vendor can put up his/her products/services for sale at a market place.
  2. Customers can go to a market place, see a catalogue of products.
  3. Customers can add products to a shopping cart.
  4. Vendors earn money when the customers pay them for the products purchased.
  5. Vendor hands over the products to the customer.

This sequence of steps is called a use case and describes the buyer-seller transactions. You can apply the same four steps whether the business is a brick-and-mortar store, an e-Commerce website or a mobile commerce app. Why, it can even be such that the system sends a daily email to customers who sign up. Then the customers can mail back with the list of items they want. WhatsApp messages can be sent and received for sale of goods.

In clean architecture, writing robust code for the use case and the business rules is considered top priority. The method of delivery such as a website, mobile app or email is called a detail. Although an important part of the puzzle, the medium of delivery is considered a later priority after the code for the rules of the use case have been developed. As a finished product, the code is arranged such that the program’s purpose and the use cases it tries to solve stand out, whereas things like the delivery mechanism are pushed deep down.

Software is designed in layers

Like an onion, clean architecture ensures that your software is designed in layers, such that the outer layers can be peeled away and replaced with alternatives, but your core remains the same.

Clean architecture builds software in layers

The core layer of your software will contain the components most critical to your system, i.e. the use cases and all the components that directly make up the use cases. In a shopping system, it would be products, a way to display products, shopping carts, money and transactions. These components will never change and they form the backbone of the system. In clean architecture, these are called the entities.

A layer outside the core components will be a set of processes and rules that drive the system. In a shopping system, the processes are: the process of a vendor using a product listing to display products to a customer, the process enabling a customer to add products to a cart, the process by which a customer pays for products, the process by which a store delivers products to a customer and the process by which a dissatisfied customer returns a product to the vendor and gets part of or the entire money back. These processes are called use cases. Each use case contains a narrative of how the it takes place. E.g. how a customer browses for products and puts them into his/her shopping cart. Processes bind the entities together and make sure that they flow from one part of the system to another. E.g. product going from the vendor to customer and the money vice-versa. Processes too rarely change.

Next comes the layer by which processes talk to the systems outside the core. E.g. how to talk to payment gateways like RuPay or PayTM to accept payment from the customer. This layer is called the gateway layer and bears the brunt of changes to the systems outside. It protects the processes and entities from change. E.g. if a business decides to switch from brick-and-mortar to online or from website to mobile app or if more payment systems like UPI are introduced as ways for customers to pay.

Finally, we look at the layer with systems outside. These systems are necessary for the system to work, but one system can be swapped for another if the business decides so. The change should be smooth and should not affect the functioning of the system drastically. E.g. a product catalogue can be stored inside a database or on an Excel sheet. A user can be given the option to pay either in cash, leading to the manual entry of the transaction by a clerk or by using a credit card, leading to an automated entry once the payment gateway approves. Users may shop using a mobile app, a web site or over telephone placing an order through the business’s call centre.

Individual components of the software can be tested and verified

By factoring software into layers and components within layers, each component can be tested and assured to be working independent of all other parts of the system. This is called unit testing and is a requirement for assuring the quality of software. You can read about the philosophy of unit testing in the post Unit Testing and Integration Testing.

Also watch…

Here is the link to the enlightening video on software architecture by ‘Uncle Bob’ on YouTube.


In this first post in a two-part series, you learned how software today focuses too much on how rather than why. You learned what clean architecture is and how it is layered. In the next post, we will see how components are designed within clean architecture and how data flows from one place to another to achieve what the software is designed for.


3 thoughts on “Introduction to clean architecture: Part 1”

Leave a Reply

Your email address will not be published.