The HEXAGONAL Architecture Explained | Ports and Adapters Pattern

In this video we cover in great detail the "Hexagonal Architecture" by Alistair Cockburn, also known as the "Ports and Adapters" pattern.
This software pattern has the same main objective of the clean and onion architecture: decouple the business logic from all concerns like UI and infrastructure (e.g. DB).
I made sure to explain in detail the theory behind it but also to provide a concrete and complete code example.
GitHub Repository: github.com/marcolenzo/hexagon...
🤓 There's more on my website! (articles, scripts, code snippets, etc...): 🤓
marcolenzo.eu/
marcolenzo.eu/the-hexagonal-a...
🤝 Connect with me: 🤝
/ marcolenzo
👌Get a CodeCrafter Discount 👌
app.codecrafters.io/join?via=...
🍕 I've got an Italian accent 😅
If you have trouble understanding me, activate the closed captions! They are manually corrected.
0:00 Hexagonal Architecture Definition
1:56 Ports and Adapters
3:56 Hexagonal Architecture Clarifications
5:24 Hexagonal Architecture in Practice
9:34 Clean vs Onion vs Hexagonal Architecture
#softwarearchitecture #microservices #cleanarchitecture

[@MarcoLenzo]

Will you use port and adapters in your next application?

[@ilyasezzahid9540]

Your know how to explain difficult technicals topics. Thank you for helping us, become better developers.

[@MarcoLenzo]

Thank you very much! Knowing this content is of help is the best reward I can get for working on it 😊

[@wadeaashraf2761]

Great topic

[@MarcoLenzo]

Thank you. I really like the hexagonal architecture

[@drissaitkassimusic]

You are a jem thank you 🙏

[@MarcoLenzo]

You made my day! Thank you! 🙏

[@marko95g]

interesting topic for discuss is using hexagonal architecture with monolith modular architecture, Can you make video about it ? Can I get your opinion on whether the secondary adapter can use the primary ports directly?

[@MarcoLenzo]

Hexagonal Architecture can be used at many levels: from serverless (functions), to application (monolith / modulith) and system. I will try my best to touch this particular aspect. I might do it in a short video. If you have some questions / doubts, feel free to write them here so I get a better idea of what you have in mind. As for the second question, explain to me what the role of this secondary adapter is in your context. If we stick to the classic definition, a secondary adapter does not invoke a primary port, but I wish to figure out better what your scenario is.

[@marko95g]

@@MarcoLenzo I am making an app for college purpose. I want to use hexagonal architecture and monolith modular architecture. Problem is that I don't know how to model communication between modules. Each module has an interface (primary port) and easiest way is to bind that interface as a secondary port for module that needs to call another module. For example, I have 'Comment module' which should call 'User module', easiest way is to define user port, and than bind it to comment module as secondary port. I hope you understand my problem :D

[@MarcoLenzo]

Yes, it is clear. I think your issue is that you need an additional layer in your application that specialized in orchestrating the interactions between modules. What you are implementing is a sort of choreographed system on top of the hexagonal architecture. A choreographed system is one where each component is responsible to invoke the next one in line through a direct call or a message. You are conceptually trying to model the output port of module A as the input port of module B to model your use case. This is possible but it will make the code effectively a bit more difficult to navigate and lead to coupling between the modules. Module A needs to know about Module B. Typically, choreographed systems are implemented with an event-driven architecture where module A generates an event that can be consumed by any other module. It might happen to be module B and that's how you end up creating your flow. In such system, the output port is always generating an event and can be generic (it doesn't need to correspond to the input port of a particular module). It's way more easy if you employ orchestration where you have a central point of control (it could be a function) that defines what the flow is and invokes all the necessary modules in the correct order. You can take inspiration from the concept of Application Business Rules or Use Cases described in the Clean Architecture by Uncle Bob (Robert C. Martin). You can also understand it better if you learn about Sagas. You will find videos about both in my channel, and there's a ton of material online. Keep in mind the hexagonal architecture focused on isolation of one layer, but onion and clean architecture expanded on it by highlighting the fact your application will typically have 3 to 4 layers. You're missing that layer that glues the module together. Hope this helps! If you need more help, don't hesitate to contact me. You find more info on my website!

[@FlaviusAspra]

I know you most probably know, but your audience might get confused: A port is an interface or a collection of related interfaces. It's not necessarily just one. A port of the model can also contain classes: typically those classes for passing data into the model or reading data out of the model. Typically these are value objects and DTOs. Key point: these are part of the domain model, because the model is not allowed to depend on anything outside of itself.

[@MarcoLenzo]

Thank you for the clarification Flavius. 🙏 In this setup, do you rely on package naming to highlight what the port is? Or do you imply it?

[@FlaviusAspra]

@MarcoLenzo neither, nor. I enforce it with fitness functions. "Naming" something in technical ways goes against DDD's ubiquitous language and towards pure fabrications. I try to minimize the number and "blast radius" of pure fabrications in domain models. Typical example, no "ProductRepository", better: "ProductDataStorage" (as to not confuse with storage places of products). Not perfect still, but it is what it is. Edit: I've re-read your question carefully: yes, they are grouped together, but the above still holds.

[@MarcoLenzo]

Understood 😊 You gave me a good idea for a follow up video. I think adding fitness functions to the sample repository would be an interesting exercise showing how we can enforce the design (hexagonal or whatever we use in our app).

[@FlaviusAspra]

​@MarcoLenzo wasn't aware of the repo, but I checked it out now. I think we work quite similarly and you got many things just right. Examples from others that I've seen were utterly wrong, with the domain importing all kind of stuff. I have a feeling that we would work well together, we probably wouldn't agree on everything, but we would understand each other and let it go. Which is healthy - bringing other perspectives. Perspective 1: I'm not a big fan of words like "services" in the domain. It's a pure fabrication, it steals the word "service" from projects which offer business services - and that is most. Whenever I can, I get rid of that abstraction and I have my usecase as a class. Perspective 2: I pack the parameters of the use case in VOs and pass them into the model rather than the raw values. I feel stronger about perspective 1, and I'm fine with living with perspective 2. But I think in my case P2 is motivated by another situation which is very sensitive in the way I approach it: Some VOs which are enums and each value is bound to a business process also has a factory method for the business process inside. Classical example: the request parameter "accountOperation" which can be close, verify, ... I know most programmers twitch at this factory method being there and say "but factory class", and all I'm thinking is: I already put the if in the VO to validate it, why make the same if somewhere else? And all bugs that would come with this. It would also imply having a VO getValue() method which makes ME twich: the VO is THE value, in OO there shouldn't be yet another value behind the value. How do you view this idea of VO::createBusinessStrategy()?

[@MarcoLenzo]

Flavius I'm sure we would work well together. I like to learn and try new approaches, especially if driven by someone knowledgeable and passionate like you. Based on many interactions we had, I know that I am more lenient than you when it comes to applying principles in the codebase written by other teams. To be honest, I'm intrigued by your approach and I'm just waiting for the right occasion to try it. That said, regarding P1 I've seen many codebases with anemic models, no use cases, and just a bunch of services. That is why I decided to include them along side an entity with sample behavior. I wanted developers to see something they are familiar with in the context of a pattern like hexagonal. Totally agree on P2 (avoiding raw values in the use case interface) and that is actually something I am used to do as well. Regarding the factory method tied to the business strategy, I wish I could see a sample to make sure I'm understanding well your idea. I'll try to answer anyway. What I got till now is that you wish to partition validations according to the particular business process which is selected through the VO. That makes perfect sense to me. (Just for the sake of considering tradeoffs I'm going to ask you something back...) I wonder if your use case interface is generic (i.e. a single method is used to trigger different operations); or if the same VO is used in different methods. That said I'm wondering if you considered more fine grained methods at the use case interface level / or different VOs per business process.