Clean Architecture Chapter 8 - Financial Data Mapper

Question

I’m studying Clean Architecture, and I came across a technical concept in the diagram from chapter 8. In this chapter, the author states that the Financial Data Mapper implements the Financial Data Gateway and interacts with the Financial Database.

enter image description here

However, this left me a bit confused. To me, it doesn’t make much sense for a Data Mapper to interact directly with the database. I’ve always understood the role of the Mapper as simply translating between the application’s objects and the database model (and vice versa), without performing read or write operations on the database.

Another point that puzzled me is the idea of a Mapper implementing the Gateway. Why not use a repository instead? I can’t wrap my head around a Mapper being responsible for database communication.

It’s possible that I misunderstood this part, so I apologize if my question or understanding seems naive. I also understand that the diagram’s purpose is to illustrate the OCP principle rather than detailing a practical implementation. Still, since the diagram provides an interesting high-level view of how a feature works, I decided to use it for study purposes.

• Filip Milovanović: Don't focus as much on the specific classes in this diagram - this is how CA might look like when implemented, but in principle, the classes and the details of the design here could be completely different, and it would still be Clean Architecture as long as the principles are followed. Instead, focus more on the roles the elements play, and how they contribute to the design - e.g., the interfaces provided and used by the report generator are all "owned" by the generator, and bundled together in the interactor, which allows for dependency inversion, in service of the dependency rule.
• Filip Milovanović: Also, note that in CA terminology, "entities" are not ORM entities - they are not plain data structures that model the database, but correspond to objects that have behaviors, and that capture the core business logic (Martin describes things in OO terms, but if the approach is more functional or procedural, then they would correspond to the functions implementing the business logic, plus the associated core data structures / types those functions are tied to). When he says the interactor controls the "dance of the entities", it means something like "it orchestrates the business logic code".

Answer 1

The "mapper" is not used in the same meaning as e.g. a mapstruct-mapper.

Uncle Bob uses a somewhat confusing notation here. It gets clearer, when you read the "Data Mappers" part in chapter 23.

Basically, he argues that an object relational mapper (ORM) should really be called data mapper, because ... reasons.

Now, if you replace the "financial data mapper" with an ORM like hibernate, the diagram begins to make sense.

• Tozine: This makes much more sense now. From this perspective, I could see this Mapper as a type of Repository, commonly used in DDD, right? I'll read Chapter 23 to better understand why Uncle Bob uses this terminology and the reasoning behind it. Thank you!
• Greg Burghardt: @Tozine, remember that Clean Architecture is defined in super abstract terms. This is so you can envision how almost any application written in any framework, language, or tech stack (using any number of design patterns), can fit (or be retrofitted) into Clean Architecture. Readers can adapt these ideas to applications they know once they understand how the author defines them.

Answer 2

it doesn’t make much sense for a Data Mapper to interact directly with the database. I’ve always understood the role of the Mapper as simply translating between the application’s objects and the database model (and vice versa), without performing read or write operations on the database.

Another point that puzzled me is the idea of a Mapper implementing the Gateway. Why not use a repository instead? I can’t wrap my head around a Mapper being responsible for database communication.

If you wanted to drop another box into the DataBase component and have it deal with read and write operations it wouldn't violate anything Uncle Bob has taught. What would is if you let a single DB detail creep into the Interactor component.

A big thing to notice is that the Financial Data Gateway has a <I> in the corner. Means this is an interface. Which means behavior goes elsewhere. This is an API through which to grab or toss out entities. It knows squat about the DB. Actually, it points at nothing. So all it knows about is itself.

However, Financial Data Mapper knows about the DB, the Financial Data Gateway and every damn entity. It has no <I> so this is where your behavior goes.

That's a lot. And no, you don't have to do it all at once. You're free to break this up and call it whatever you like. Just no sneaking this work back into the Interactor.

You ask,

why not use a repository instead?

To which I ask, what about these design requirements prohibits a repository?

• Tozine: Looking at your response and those of others, I conclude that the implementation itself doesn't matter much, for two reasons. First, the diagram doesn't focus on implementation per se, but on the OCP. Second, how models are implemented outside the boundaries doesn't really matter, as the core is protected by interfaces and dependency inversion. Uncle Bob has an approach different from what I'm used to, likely due to years of experience and different contexts. Perhaps this is why I’ve become so attached to simple details like the "naming" of boxes. Thank you.
• candied_orange: @Tozine OCP and DIP are considerations but what this diagram tells you more than anything else is what knows about what. That's the big lesson any UML class diagram teaches.