Clean Architecture the Right Way
Is it about oPTiMaL fOLdER stRuCTURE?
Today’s Crafting Tech Teams issue is an essay separating the fashionable from the practical when it comes to Clean Architecture. Topics we’ll cover:
Spoiler Alert: it’s not about the folder structure. Yes and no. Yes, it will impact your folder structure. No, the folder structure is not why we are doing it. Copying someone else’s “ideal, clean architecture” project structure will cause more harm than good.
Pro View: the pragmatic benefits. Why it exists. I mean—did you ask yourself why we are even talking about Clean Architecture, Hexagonal, Use Cases, VSA, etc.? How did we get here? What was before. We’ll explore that.
Contrarian View: critiques and challenges. Sometimes the project is fine as it is. And then someone on your team reads Uncle Bob’s book and watches a video and all hell breaks loose, folders moving left, right and centre!
YouTube vs. the Book: deeper understanding. As with DDD there are many more would-be practitioners compared to the number of people who have read the original book that introduced the idea. Shocking!
Join the Discussion, Live Stream. Live discussion on Thursday (Aug 3rd), 16:30 CEST. That’s today or tomorrow, depending on where you are.
Spoiler Alert: it’s not about the folder structure
“Hey Denis, what folder structure do you recommend for a fresh Clean Architecture project?”
Just shoot me please. Don’t get me wrong, I love to talk about this. However it does give me the feeling that we as tech trainer and influencers have failed our audience. Folder structure is after all a simple, fundamental concept. But Clean Architecture is not.
However, what I claim in the title of this chapter isn’t entirely accurate. You see, I can tell if a project is following sound, well-shaped Clean Architecture principles just by looking at the folder structure. In a well-architected project, that folder structure is a downstream consequence of the inner workings and cohesion towards the business needs.
I checkout the project. Look at it for 5 minutes. And understand where the important features, revenue streams, value streams and capabilities are.
Do you want the largest example of Clean Architecture? Check out Amazon’s AWS Product Catalog. Their code organization, developer experience and API documentation, they all match the public-facing business intent of the company (AWS in this case).
Pro View: the pragmatic benefits
I consider it ironic that clean architecture at its core does not introduce any new concepts, principles or architectural paradigms. In comparison, the very first patterns book—A Pattern Language by Christopher Alexander—includes over 400 patterns for how to build communities, towns, houses, buildings, utility structures and more. How the human elements dictate the natural structure of things: Fibonacci. Natural ratios. Golden ratios. Social status.
The book Patterns of Enterprise Application Architecture by Martin Fowler was based on that model of writing and has achieved similar success and immortality.
So…
What is it all about?
Let me simplify it for you:
“Clean Architecture is Enterprise-level OO programming using SOLID principles applied to Systems Design.“
Let’s break that down!
Why OO programming?
OO programming became a cornerstone in enterprise software in the late 2000s. Startups later adopted this trend with easy-DX frameworks modelled on Spring and Hibernate (Entity Framework and ASP.NET in C#, Doctrine and Symfony in PHP, Prisma, Angular1 in javascript).
The sister-book Clean Code, along with the craftmanship books of that era: TDD by Kent Beck and Domain-driven Design by Eric Evans create a pinnacle of technical excellence upon which modern software development processes are founded in a manner where the basis of business rules and application code are built upon object-oriented abstractions and frameworks, rather than direct machine code.
Why SOLID?
I don’t recommend following SOLID principles religiously. I do recommend learning the philosophy behind them. SOLID, and many other design or architecture principles help us calibrate our compass for clean code. Or inversed: they help us identify Code Smells.
Code smells are signals that enable refactoring. And it is the refactoring that creates architectural and craftsmanship quality. Unlike a physical building, structure or bridge, software is often not built well with Big Design Up FRONT (BDUF). There are many reasons for this that we will go into in a later issue.
Why Systems Design?
Zoom out with me.
What produces quality writing? Refactoring (=editing) drafts.
What produces quality craftsmanship? Refactoring code smells.
What produces quality database design? Refactoring (=normalizing) database models.
What produces quality infrastructure? Refactoring (=generalising) to serve any service.
What produces quality systems design? Refactoring (=cleaning) of implementation architecture.
We commit to all these steps not because it’s easy. We commit because there is market demand and validation to the value our software provides.
So the core question isn’t about ideal folder structure in a greenfield project. The core question is how do I clean up my architecture mess now that it’s profitable?
Successful business produces codebases they hate. And then you refactor them.
It is the Cohesion of Business Capability and Technology that communicate a Clean Architecture:
You understand what the business does by looking at the code
You grasp what the code does by understanding the business
In case you mix up Coupling and Cohesion often like I do, here’s a summary I wrote on a while ago:
Contrarian View: critiques and challenges
“Ok Denis—you got me. Nice sweet talk. What’s the catch?”
In a way, the catch is that Clean Architecture is not suitable for beginners. Clean Architecture is not a fundamental skill. It is an advanced, highly specific solution for complex projects that requires a solid understanding of modern software practices, combined with the experience and discipline to execute them.
That’s the prerequisites to start.
I wish it was any other way. Enthusiastic beginners do praise it for being easier to adopt a CA project and it’s easier to work in and reason about. However, getting the project to that state likely required a lot of grit from your best developers and architects. This is no coincidence, which is why it is rare. Because it is rare, it is cherished at an inflated price range.
It attracts beginners for the wrong reason and you end up with code like this:
IBooking
BookingImpl
BookingFacade
BookingWebPort
BookingResponse
BookingManager
BookingManagerImpl
We’ve all seen this. We all hate it. There’s nothing wrong with code like this, out of context, on the surface. But it does make you wonder about the cohesion of a system.
The Death of Frameworks and ORMs
There is a deeper, more begrudging aspect to Clean Architecture. Over the decades I witness many great frameworks abandoned. jQuery, Angular, moment.js, Zend Framework, JavaFX, Java core language (favoring Kotlin and Clojure), Ruby on Rails.
And this only touches the surface, not taking into account version incompatibilities within the long-lived tech brands.
As a long-lived principle, Clean Architecture advocates not coupling to frameworks, infrastructure and ORMs. But this is quite impractical for businesses that need to fail fast. Businesses that don’t have longevity in mind on the current tech stack.
Let’s be real. You won’t change your database from MySQL to Postgres. Being able to test the DB query-centred computation of business rules on an in-memory database is a capability only large enterprises require with strict guarantees of testing and correctness.
That’s not to say these practices aren’t recommended. Unfortunately—and you are not going to like this, even though you’re nodding— the hard truth is that your team, business and organization are simply not experienced enough in tech and your industry to benefit from any of this.
YouTube vs. the Book: deeper understanding
YouTube audiences have a predisposition to over-value visual details, so naturally everyone’s drawn to the layers of clean architecture. I love playing Architecture Bingo.
What is Architecture Bingo? Well why don’t you check out for yourself in my podcast with fellow Tech Guru Milan Jovanović:
The consequences are obvious: there’s too many videos on layers and separation and not enough videos on cohesion and architecture principles. This emphasis on the superficial topics creates a skewed impressions that Clean Architecture is one single thing, rather than a set of principles with competing, mutually exclusive options.
The readers of Clean Architecture will quickly recognize the book’s self-proclaimed chapter of incompleteness. Yes, that one! The magic chapter in the book that isn’t. It covers all the secrets for why we keep having this confusion nearly 20 years after the book was released. Was it pragmatic? Perhaps—it’s certainly a good marketing ploy to sell more books.
Be it as it may, it is one of the rare books that has survived the test of time and is gaining more traction every decade.
I would attribute its success to the developer ergonomics introduced by the .NET community and the focus on microservices and cloud technologies in the current decade.
💬🎥 Join the Discussion, Live Stream
Weekly live stream tomorrow. Join dozens of enthusiasts in chat, we even have a few big names and influencers RSVP’s on LinkedIn. Come ask, learn, have a contrary view, let’s disagree and discuss.
