1. Implementation Is a UML Diagram
The Clean Architecture implementation is essentially a UML diagram for a specific application or type of applications. And this the most important insight I have gained over the years. This diagram bridges abstract principles and concrete code, defining application units, their relationships, boundaries, and dependencies.
So, the natural process of turning Clean Architecture into a codebase is as follows:
+-----------------------------+
| Clean Architecture |
| Principles |
+-----------------------------+
|
v
+-----------------------------+
| UML Diagram |
| (Units, Boundaries, Flow) |
+-----------------------------+
|
v
+-----------------------------+
| Application Codebase |
| (Concrete Implementation) |
+-----------------------------+
For a typical backend application written in Java, a well known Clean Architecture implementation has existed for many years:
Clean Architecture. A craftsman’s guide to software structure and design. Robert C. Martin. Copyright © 2018 Pearson Education, Inc.
However, this implementation does not directly apply to reactive frontend applications, which rely heavily on the observer pattern. In practice, attempting to adapt it to the frontend context often leads to unnecessary complexity, as it introduces excessive code solely for this adaptation, without providing real benefits. This is the main reason I often hear that Clean Architecture is painful for frontend applications.
Nevertheless, the principles of Clean Architecture are universal. An implementation tailored for a typical frontend application - with a store and API integration - can be slick, simple, and effective, as shown below:
This implementation can be used with any modern reactive frontend framework, such as React, Vue, Svelte, or Angular.
2. DDD Terminology Can Obscure Clean Architecture
A huge source of confusion in projects built with Clean Architecture is the pervasive use of Domain-Driven Design (DDD) terminology throughout the codebase, often without explicit reason and explanation. While Clean Architecture and DDD are both valuable approaches, they have distinct concepts, and terminology. When a developer joins a project structured with Clean Architecture, they may expect to see CA-specific layers and units (such as use cases, gateways, controllers, and presenters). However, in practice, much of the code may operate almost exclusively with DDD concepts - like aggregates, repositories, domain services, and structured in layers that resemble DDD's bounded contexts.
This heavy reliance on DDD terminology, without clear mapping to Clean Architecture concepts, can make it difficult for developers to orient themselves, leading to confusion or even rejection of the architecture approach. The lack of explicit boundaries or documentation explaining how DDD elements fit within the CA structure further compounds the problem. To improve clarity and onboarding, it is important to acknowledge the use of DDD, provide guidance on how DDD and CA concepts relate.
3. Codebase Evolution: The Overlooked Factor
With a UML diagram that clearly defines the units of an application, developers have a blueprint for how the system should be structured. However, a common pitfall is to equate each unit in the diagram with a separate file in the codebase from the very beginning. This approach can lead to unnecessary fragmentation, boilerplate, and a proliferation of files that are difficult to navigate and maintain, especially in the early stages of a project.
Instead, when the architectural units are well understood, it is often more effective to inline related logic and keep the codebase simple at first. As the application grows, these units can be gradually extracted into their own files or modules as needed. This incremental extraction helps keep the codebase manageable and avoids premature abstraction, but requires discipline to refactor and extract units as complexity increases.
4. Templates Undermine Agility
Every project has unique requirements, and Clean Architecture encourages teams to make architectural decisions at the right time, based on actual needs rather than assumptions. Relying on templates can lead to premature abstraction, unnecessary complexity, and a false sense of security. Instead, it is better to use templates as learning tools or references, while allowing the architecture to grow organically in response to real-world challenges and changes.
Conclusion
Effective application of Clean Architecture requires a bridging implementation represented as a UML diagram. For frontend applications built with modern reactive frameworks, blindly following backend-oriented CA implementation or relying on templates can introduce unnecessary complexity and hinder agility. It is also important to understand the distinctions between Clean Architecture and Domain-Driven Design, and to evolve the codebase organically - making decisions as real needs arise. Teams that understand these principles will avoid headaches throughout the entire application lifecycle.
Top comments (0)