Which Clean Architecture Areas do Gateways interfaces and their implementations belong to?

[徳川武]

Dear everybody, 

I am a little bit confused about position of gateways in the clean architecture diagram (chapter 22, "The dependency rule"). 

Talking about gateways , it is required to distinguish:

* The interfaces
* The implementation of these interfaces

The TypeScript example:

// === Interface ======================================
interface UsersGateway {
 
  retrieveSelection: (requiestParameters: UsersGateway.SelectionRetireving.RequestParameters) =>
       Promise<UsersGateway.SelectionRetireving.ResponseData>;

}

namespace UsersGateway {
  export namespace SelectionRetireving {

    export type RequestParameters = Readonly<{
      paginationPageNumber: number;
      itemsCountPerPaginationPage: number;
      fullOrPartialName? string;  
    }>;

    export type ResponseData = Readonly<{
      totalItemsCount: number;
      filteredItemsCount: number;
      itemsForCurrentPaginationPage: ReadonlyArray<User>;
    }>;
  }
}


// === Implementation =======================================
class UserMySQL_Gateway implements UserGateway {
  retrieveSelection(
    requiestParameters: UsersGateway.SelectionRetireving.RequestParameters
  ):  Promise<UsersGateway.SelectionRetireving.ResponseData> {
    // Implementation including SQL code here
  }
}

Now the question: in the Clean Architecture diagram, the "Gateways" in the green ring (the third one from) are interfaces of their implementations? If one of them, there is another?

My assumptions

Although the frameworks must be in the outer (blue) ring and, I have not seen the framework-independent Controllers and/or Presenters before. Thus, the "gateways" in the green ring could be the implementations which depends on some framework or RDBMS (thus assumption is matching with Interface adapter concept).

If so, there is the gateway interfaces? The table of contents of Chapter 20 Business rules is:

• Entities
• Use Cases
• Request and Response Models
• Conclusion

Are mentioned above Request and Response Models the gateway interfaces?

[Wilson Neto]

It`s a really great question...

IMO the gateways implementations are on the green ring, the interface adapters (or the adapters of the interfaces, so, they are the implementation of the interfaces, the adapters between what your use cases need and the external world of DBs/ORMs/Frameworks and etc., they get the world mess and translate in a beautiful interface that your use case need.)

And yes, in some diagrams in the book, we can see the interfaces near the use cases; IMO the best place for these interfaces is in the use cases layer or even in the entities layers if we are following a more DDD approach.

I hope it helps,
best regards.

[Damian Rossney]

This is a good question. In my opinion these concepts are better explained in Uncle Bob's talks. Check out this one, for example: https://www.youtube.com/watch?v=WpkDN78P884&feature=share&si=ELPmzJkDCLju2KnD5oyZMQ. Search YouTube for Robert Martin (or Bob Martin) and Architecture to find several versions of this talk.

One of the reasons that I like the talks better is that they use clearer diagrams, at least in my view.  Here is a good one from the talks:

You can find essentially the same diagram on page 208 of the Clean Architecture book. As you can see, all of the interface objects (along with the Request Model and Response Model data transfer objects) are defined inside of the "use case" layer. They wrap the Use Cases and define the API for interacting with them. In this diagram, the triangle-shaped arrows indicate what object will *implement* the interface, while the pointy arrows indicate what objects will use (or invoke) the interface to interact with the object that implements the interface. This is a very important detail to understand.

For example, in this diagram, the Boundary Interface defines the methods and method signatures that must be implemented by Interactor objects. Since this interface is clearly defined, the Controller objects know exactly how to invoke those methods on the Interactor Object they must use to complete their intended task.

Turning to your question on Gateways, it is clear the Entity Gateway must be defined inside the Use Case layer, but be implemented outside of the Use Cases. This implementation is then passed in to the Interactors (and, perhaps, Entities) via dependency injection.

The confusion comes from the over-simplification of the diagram on page 203 of the book (and in the Clean Architecture blog post). In this diagram the Gateways (and Presenters) shown in the green ring are the implementations of the Gateway Interfaces (and Presenter Interfaces) defined in the Use Case layer. This is clarified in the color-coded explanation in the bottom-right of the diagram, but it is not really clear to me (especially since this diagram is printed in black and white in my copy of the book).

I hope this is helpful!

Damian