Feedback on the Common web application architectures article

[vsfeedback]

Type of issue

Other (describe below)

Description

This issue has been moved from a ticket on Developer Community.

---

To whom it may concern,

I am writing to express my concern and dissatisfaction with the article titled “Common web application architectures” that is published on the Microsoft Learn website. In particular, I have an issue with the section that describes the Clean Architecture.

The article claims that the Clean Architecture is a generic term that has gone by many names over the years, such as Hexagonal Architecture, Ports-and-Adapters, Onion Architecture, etc. It then proceeds to describe a custom architecture that has nothing to do with the original Clean Architecture as defined by Robert C. Martin in his book of the same name.

This is misleading, inaccurate, and disrespectful to the author and his work. The Clean Architecture is not a generic term, but a specific architecture that has a clear definition and structure. It is based on a set of principles and rules that aim to make software systems more understandable, maintainable, testable, and independent of frameworks, databases, or external agencies. It consists of four main layers:

1. Enterprise Business Rules (Entities);
2. Application Business Rules (Use Cases);
3. Interface Adapters;
4. Frameworks and Drivers.

The architecture that the article describes introduces new terms and layers that are not part of the Clean Architecture, such as Application Core, Infrastructure, and UI. It also mixes up different architectures and patterns that are not equivalent or interchangeable with the Clean Architecture, such as Hexagonal Architecture, Ports-and-Adapters, Onion Architecture, etc.

These architectures and patterns may have some similarities or overlaps with the Clean Architecture, but they are not the same thing. They have different origins, definitions, structures, and goals. They may also have different advantages and disadvantages depending on the context and requirements of each project. To lump them together under one name and present them as one architecture is confusing and misleading for the readers.

Therefore, I urge you to change the title and content of the section that describes the Clean Architecture. You should either describe the Clean Architecture as it is defined by Robert C. Martin in his book, without making up new terms and layers, or you should not mention the Clean Architecture at all and use a different name for your custom architecture. This way, you will avoid misinforming and misguiding your readers and respect the author and his work.

Thank you for your attention and consideration.

Sincerely,

Dmytro Turskyi

---

Original Comments

Tracy Wang [MSFT] on 6/18/2023, 05:34 PM:

We have converted this feedback item to a suggestion. This change was done to better reflect the feedback’s nature. It will allow other developers to easily find it and engage on it.

Feedback Bot on 6/18/2023, 07:34 PM:

Thank you for taking the time to provide your suggestion. We will do some preliminary checks to make sure we can proceed further. You will hear from us in about a week on our next steps.

Page URL

https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures

Content source URL

https://github.com/dotnet/docs/blob/main/docs/architecture/modern-web-apps-azure/common-web-application-architectures.md

Document Version Independent Id

b227c667-82ae-97ef-c175-7e17051c5ab2

Article author

@ardalis

Related Issues

[Rick-Anderson]

@ardalis owns this.
@Turskyi what about

Clean Onion architecture

Applications that follow the Dependency Inversion Principle as well as the Domain-Driven Design (DDD) principles tend FREQUENTLY to arrive at a similar architecture. This architecture has gone by many names over the years. One of the first names was Hexagonal Architecture, followed by Ports-and-Adapters. More recently, it's been cited as the Onion Architecture AND BORROWS SOME ELEMENTS FROM Clean Architecture. The latter name, Clean Architecture, is used as the name for this architecture in this e-book.

I think we should replace this with Enterprise App Patterns - Modern Web App (MWA) once it's released.

[Turskyi]

Hi @Rick-Anderson,

Thank you for your response and the suggestion to transition to “Enterprise App Patterns - Modern Web App (MWA)” in future updates. While I appreciate the consideration, I’d like to expand on a few points that I believe are important to address to avoid any further confusion for readers.

Firstly, there are other parts of the documentation that continue to use the term "Clean Architecture," including images and diagrams that explicitly label it as such. Simply replacing the textual references won’t be enough to correct the misrepresentation—these images will also need to be updated accordingly. The visual elements play a significant role in shaping how readers interpret the content, so they must accurately reflect any terminological changes you make.

Additionally, I noticed that you suggested pivoting from “Clean Architecture” to “Onion Architecture” as part of this update. While this could be a good alternative, it’s important to note that "Onion Architecture" also has a very specific definition and structure, as outlined in the original article by Jeffrey Palermo (https://jeffreypalermo.com/2008/07/the-onion-architecture-part-1/). Can Microsoft guarantee that the interpretation described in your documentation doesn’t deviate from the implementation presented by Palermo? If your version introduces different terms, layers, or structures, it risks misrepresenting Onion Architecture in the same way that Clean Architecture was misrepresented.

Based on what I've seen, it feels like there’s an intention to create a hybrid approach that borrows from both Clean and Onion Architecture but follows its own path. If that’s the case, perhaps the best solution would be to come up with a new name altogether, one that better reflects the unique aspects of your approach. You could briefly mention that this new architecture was inspired by both Clean and Onion Architecture and acknowledge the specific layers and components you’ve borrowed. However, by giving it a distinct name, you avoid implying that it is the same as these well-defined existing patterns.

This would not only provide more clarity for your readers but also ensure that both Robert C. Martin’s Clean Architecture and Jeffrey Palermo’s Onion Architecture are respected in their original forms.

Thanks again for considering my feedback. I hope this helps in refining the content to better serve the developer community.

[Rick-Anderson]

@Turskyi thanks for your detailed response. The changes I proposed were just a sample of the direction I thought the doc should go.

Based on what I've seen, it feels like there’s an intention to create a hybrid approach that borrows from both Clean and Onion Architecture but follows its own path. If that’s the case, perhaps the best solution would be to come up with a new name altogether, one that better reflects the unique aspects of your approach. You could briefly mention that this new architecture was inspired by both Clean and Onion Architecture and acknowledge the specific layers and components you’ve borrowed. However, by giving it a distinct name, you avoid implying that it is the same as these well-defined existing patterns.

I agree.

Clean architecture makes DI the cornerstone of the doc, while Reliable web app pattern for .NET mentions DI:

The reference implementation uses Polly to set up the ASP.NET Core dependency injection. Polly enforces the Retry pattern every time the code constructs an object that calls the IConcertSearchService object.

Let's see how @ardalis responds.