1
00:00:00,040 --> 00:00:02,400
Welcome to the deep Dive, the 
show engineered to give you the 

2
00:00:02,400 --> 00:00:05,720
most important knowledge and 
insights really fast. 

3
00:00:05,800 --> 00:00:08,720
You provide the sources we dive 
in, pulling out those key 

4
00:00:08,720 --> 00:00:10,200
Nuggets to get you properly 
informed. 

5
00:00:11,080 --> 00:00:13,960
Today we're taking a pretty 
fascinating plunge into software

6
00:00:13,960 --> 00:00:16,720
design, looking at something 
called hexagonal architecture. 

7
00:00:17,040 --> 00:00:19,960
Our mission, and we're guided by
the excellent source you sent 

8
00:00:19,960 --> 00:00:23,760
over, specifically a nine 
hexagonalarchitecture.pdf by 

9
00:00:23,760 --> 00:00:26,000
Marco Tulio. 
Valente is basically to 

10
00:00:26,000 --> 00:00:29,920
demystify this pattern, well, 
unpack its core ideas, look at 

11
00:00:29,920 --> 00:00:32,320
the benefits, which are quite 
surprising sometimes, and show 

12
00:00:32,320 --> 00:00:35,160
you why it's such a well, a game
changer for building software 

13
00:00:35,160 --> 00:00:37,280
that lasts and adapts. 
Exactly. 

14
00:00:37,280 --> 00:00:38,760
And it's not just another 
buzzword. 

15
00:00:38,840 --> 00:00:41,960
You know, it's, it's really a 
fundamental way to think about 

16
00:00:41,960 --> 00:00:45,240
structuring applications so they
stay robust, adaptable, and 

17
00:00:45,320 --> 00:00:47,520
maybe most importantly, testable
over time. 

18
00:00:47,840 --> 00:00:49,400
It's about building for the long
haul. 

19
00:00:49,600 --> 00:00:52,360
And you are definitely going to 
get some clarity here. 

20
00:00:52,440 --> 00:00:54,480
We'll even touch on why it's 
called hexagonal. 

21
00:00:54,480 --> 00:00:57,240
That's always a fun bit and how 
this idea helps solve some 

22
00:00:57,240 --> 00:00:59,440
really common and developer 
frustrations. 

23
00:00:59,720 --> 00:01:01,880
But let's start at the 
beginning. 

24
00:01:01,880 --> 00:01:04,800
Where did this come from? 
So yeah, let's unpack this. 

25
00:01:04,800 --> 00:01:07,040
This didn't just pop up 
recently, hexagonal 

26
00:01:07,040 --> 00:01:09,240
architecture. 
It was first introduced by 

27
00:01:09,240 --> 00:01:12,400
Alistair Cockburn. 
He's a big name in software way 

28
00:01:12,400 --> 00:01:16,720
back in the mid 90s. 
And get this, he first shared it

29
00:01:16,720 --> 00:01:20,280
on the wiki Wiki web, which if 
you're into tech history, that 

30
00:01:20,280 --> 00:01:22,360
was literally the first wiki 
ever. 

31
00:01:23,200 --> 00:01:25,520
Kind of a groundbreaking place 
for sharing these ideas back 

32
00:01:25,520 --> 00:01:26,920
then. 
And a real piece of Internet 

33
00:01:26,920 --> 00:01:28,240
history there. 
Definitely. 

34
00:01:28,280 --> 00:01:32,360
And at its heart it shares a lot
with other ideas like say, clean

35
00:01:32,360 --> 00:01:34,640
architecture, right? 
The goals are similar, high 

36
00:01:34,640 --> 00:01:36,680
cohesion, low coupling. 
Exactly. 

37
00:01:36,680 --> 00:01:39,560
Keep things that belong together
together, and make sure 

38
00:01:39,560 --> 00:01:41,000
different parts aren't too 
tangled up. 

39
00:01:41,400 --> 00:01:44,920
But what's the real kicker here?
The core idea that makes it so 

40
00:01:44,920 --> 00:01:48,680
different, especially for making
adaptable systems and making 

41
00:01:48,680 --> 00:01:51,760
testing easier? 
The real aha, the moment, I 

42
00:01:51,760 --> 00:01:54,960
think, is how it forces this. 
You could call it strategic 

43
00:01:54,960 --> 00:01:57,480
indifference. 
It does this with a really clear

44
00:01:57,480 --> 00:02:00,200
separation. 
You basically split your code 

45
00:02:00,200 --> 00:02:02,320
into two camps. 
You've got your domain classes 

46
00:02:02,320 --> 00:02:04,400
on one side. 
That's your core stuff, the 

47
00:02:04,400 --> 00:02:06,800
business logic, the rules that 
make your software unique. 

48
00:02:07,200 --> 00:02:09,520
Then on the other side you have 
external classes. 

49
00:02:09,880 --> 00:02:11,760
This is everything that talks to
the outside world. 

50
00:02:11,760 --> 00:02:14,880
The UI, databases, maybe 
external API's, payment systems,

51
00:02:14,880 --> 00:02:17,880
message queues, all that and the
absolute key rule. 

52
00:02:18,040 --> 00:02:20,920
The foundation is your domain 
classes must never deend 

53
00:02:20,920 --> 00:02:22,560
directly on those external 
classes. 

54
00:02:22,760 --> 00:02:25,640
Your core logic shouldn't care 
if it's talking to SQL Server or

55
00:02:25,640 --> 00:02:28,320
Postgres, or if the UI is web or
mobile. 

56
00:02:28,600 --> 00:02:30,480
Strategic indifference. 
I like that. 

57
00:02:30,880 --> 00:02:34,320
So if the domain is kept 
independent like that, what's 

58
00:02:34,320 --> 00:02:37,680
the biggest practical win for, 
say, a development team or the 

59
00:02:37,680 --> 00:02:39,960
business itself? 
What does that separation really

60
00:02:39,960 --> 00:02:41,560
unlock? 
It's really about future 

61
00:02:41,560 --> 00:02:42,720
proofing. 
That's the big one. 

62
00:02:42,960 --> 00:02:46,160
Because the core logic is 
decoupled, you get incredible 

63
00:02:46,160 --> 00:02:47,160
flexibility. 
Think about it. 

64
00:02:47,160 --> 00:02:50,800
Maybe the company wants to 
switch database vendors or 

65
00:02:51,000 --> 00:02:54,760
completely redo the UI from, I 
don't know, a desktop app to a 

66
00:02:54,880 --> 00:02:57,280
web app, then add a mobile app 
later. 

67
00:02:57,800 --> 00:03:00,240
Usually those changes ripple 
through everything, right? 

68
00:03:00,280 --> 00:03:03,360
You end up rewriting core logic.
Yeah, that sounds painfully 

69
00:03:03,360 --> 00:03:05,560
familiar. 
But with hexagonal, that core 

70
00:03:05,560 --> 00:03:08,520
domain logic, it stays mostly 
untouched. 

71
00:03:08,520 --> 00:03:11,960
It's like having this universal 
brain for your software that can

72
00:03:11,960 --> 00:03:14,720
just plug into different 
technologies without needing a 

73
00:03:14,720 --> 00:03:17,680
major operation. 
And it means you can even reuse 

74
00:03:17,680 --> 00:03:20,760
those valuable domain classes 
across different platforms. 

75
00:03:21,000 --> 00:03:23,680
Same business rules for web and 
mobile for instance. 

76
00:03:23,680 --> 00:03:25,480
OK. 
And I can immediately see how 

77
00:03:25,480 --> 00:03:28,000
that would make testing much, 
much easier. 

78
00:03:28,400 --> 00:03:31,840
If the core rules don't care 
about the database or the UI, 

79
00:03:31,840 --> 00:03:35,080
testing them must be simpler. 
Oh, absolutely, massively 

80
00:03:35,080 --> 00:03:37,440
simpler. 
When your domain classes are 

81
00:03:37,440 --> 00:03:41,320
isolated from all that external 
mess, how data is stored, how 

82
00:03:41,320 --> 00:03:44,680
users click buttons, writing 
tests for your actual business 

83
00:03:44,680 --> 00:03:48,640
logic becomes much faster, 
easier, and way more reliable. 

84
00:03:49,080 --> 00:03:51,960
You don't need to spin up a 
whole database or fake AUI just 

85
00:03:51,960 --> 00:03:53,600
to check if your calculation is 
right. 

86
00:03:54,080 --> 00:03:56,080
Test the core rules in 
isolation. 

87
00:03:56,120 --> 00:03:58,000
It speeds things up. 
Cut sound bugs. 

88
00:03:58,120 --> 00:03:59,840
Huge win. 
That makes total sense. 

89
00:03:59,960 --> 00:04:02,720
So for someone trying to picture
this, how is it usually 

90
00:04:02,720 --> 00:04:04,520
visualized? 
Is there a standard diagram? 

91
00:04:04,560 --> 00:04:06,880
Yeah, there is. 
The most common way is using 2 

92
00:04:06,880 --> 00:04:09,440
concentric hexagons, like a 
smaller hexagon inside a larger 

93
00:04:09,440 --> 00:04:11,280
one. 
Your domain classes, the core 

94
00:04:11,280 --> 00:04:14,440
logic, they live right in that 
inner hexagon, then surrounding 

95
00:04:14,440 --> 00:04:16,480
them in the outer hexagon. 
That's where the adapters live. 

96
00:04:16,480 --> 00:04:18,279
We'll get to those. 
And then everything, external 

97
00:04:18,279 --> 00:04:21,680
databases, UIS, other services, 
they live completely outside 

98
00:04:21,680 --> 00:04:23,480
both hexagons. 
They only interact through 

99
00:04:23,480 --> 00:04:25,960
defined boundaries. 
That image of the nested 

100
00:04:25,960 --> 00:04:28,920
hexagons is pretty iconic. 
But why hexagons? 

101
00:04:29,200 --> 00:04:32,360
Why that shape, specifically? 
Cockburn had a reason, didn't 

102
00:04:32,360 --> 00:04:33,840
he? 
Something about the faces He 

103
00:04:33,840 --> 00:04:34,960
did. 
Yeah, it's actually quite neat, 

104
00:04:34,960 --> 00:04:36,960
Cockburn said. 
The shape wasn't random. 

105
00:04:37,560 --> 00:04:40,880
Each face of the hexagon 
represents a different reason or

106
00:04:41,680 --> 00:04:44,120
interface for the application to
talk to the outside world. 

107
00:04:44,440 --> 00:04:47,520
So you might have one face for 
user interaction, another for 

108
00:04:47,520 --> 00:04:50,680
saving data, another for talking
to a payment system, maybe one 

109
00:04:50,680 --> 00:04:53,640
for sending notifications. 
It helps visualize those 

110
00:04:53,680 --> 00:04:56,640
distinct connection points. 
The different ports essentially.

111
00:04:56,640 --> 00:04:59,320
Exactly. 
Which leads us nicely to what 

112
00:04:59,320 --> 00:05:03,160
Cockburn himself later called 
the real heart of it, ports and 

113
00:05:03,160 --> 00:05:05,360
adapters. 
So what's a port here? 

114
00:05:05,520 --> 00:05:07,440
Not a network port, obviously, 
right? 

115
00:05:07,440 --> 00:05:10,080
Not physical. 
In software terms, a port is 

116
00:05:10,080 --> 00:05:12,360
basically an interface in your 
programming language. 

117
00:05:12,520 --> 00:05:14,760
Things like a Java interface or 
AC Sharp interface. 

118
00:05:14,760 --> 00:05:17,400
It's a contract. 
It defines a set of operations 

119
00:05:17,400 --> 00:05:20,360
or capabilities, either things 
the domain provides to the 

120
00:05:20,360 --> 00:05:23,160
outside or things the domain 
needs from the outside. 

121
00:05:23,240 --> 00:05:24,480
OK. 
So it's a contract. 

122
00:05:24,680 --> 00:05:26,120
Yeah, and there are two main 
types. 

123
00:05:26,240 --> 00:05:30,120
First, provided ports, sometimes
called provided interfaces. 

124
00:05:30,360 --> 00:05:33,280
These handle communication 
flowing from outside into the 

125
00:05:33,280 --> 00:05:35,320
domain. 
They define the services the 

126
00:05:35,320 --> 00:05:38,960
domain offers, like if an 
external system wants to search 

127
00:05:38,960 --> 00:05:42,920
for a book in our library 
example, it uses a provided port

128
00:05:43,000 --> 00:05:44,720
that exposes a search books 
method. 

129
00:05:44,880 --> 00:05:47,560
It's the domain's API basically.
Got it outside in. 

130
00:05:48,120 --> 00:05:51,640
Then you have required ports or 
required interfaces. 

131
00:05:51,880 --> 00:05:54,000
These are the opposite. 
They're used when the domain 

132
00:05:54,000 --> 00:05:55,560
needs something from the outside
world. 

133
00:05:55,760 --> 00:05:58,360
They declare capabilities the 
domain depends on. 

134
00:05:58,360 --> 00:06:01,600
So if the domain needs to save 
data, it doesn't know how to 

135
00:06:01,600 --> 00:06:04,840
save to a specific database, it 
just uses a required port that 

136
00:06:04,840 --> 00:06:07,160
says hey I need something that 
can save this data. 

137
00:06:07,280 --> 00:06:09,640
OK, so the ports are the 
contracts, the definitions, then

138
00:06:09,640 --> 00:06:12,760
the adapters must be the things 
actually doing the work, making 

139
00:06:12,760 --> 00:06:15,160
the connections. 
They sit in that outer hexagon, 

140
00:06:15,600 --> 00:06:17,840
kind of mediating everything 
like translators. 

141
00:06:18,000 --> 00:06:19,440
Translators is a great way to 
put it. 

142
00:06:19,640 --> 00:06:22,160
Yes, the adapters of the 
translators, they live in that 

143
00:06:22,360 --> 00:06:26,360
outer hexagon bridging the gap 
between the domains abstract 

144
00:06:26,360 --> 00:06:29,360
ports and the concrete real 
world technologies. 

145
00:06:30,040 --> 00:06:32,920
And they work in two main ways. 
First, they take calls from an 

146
00:06:32,920 --> 00:06:36,040
external system, like a REST 
request coming in, and they 

147
00:06:36,040 --> 00:06:38,720
translate that into a call to 
the right method on one of the 

148
00:06:38,720 --> 00:06:42,640
domains provided ports. 
The adapter knows REST, but the 

149
00:06:42,640 --> 00:06:45,080
domain only knows its own 
business operation defined by 

150
00:06:45,080 --> 00:06:47,120
the port. 
It decouples the domain from 

151
00:06:47,120 --> 00:06:49,040
HTTP, Jason, all that stuff, 
right? 

152
00:06:49,360 --> 00:06:52,800
Second, adapters handle calls 
going the other way, from the 

153
00:06:52,800 --> 00:06:56,120
domain out to external system. 
When the domain uses a required 

154
00:06:56,120 --> 00:06:58,800
port, like I need to save this, 
an adapter catches that. 

155
00:06:59,000 --> 00:07:01,840
It then translates that abstract
request into specific commands 

156
00:07:01,840 --> 00:07:03,560
for whatever external system is 
plugged in. 

157
00:07:03,560 --> 00:07:06,520
Maybe SQL commands for a 
database, or calls to a third 

158
00:07:06,520 --> 00:07:09,280
party API. 
Those adapters handling data 

159
00:07:09,280 --> 00:07:10,920
persistence? 
They're very often called 

160
00:07:10,920 --> 00:07:13,640
repositories. 
That really clarifies the roles.

161
00:07:13,960 --> 00:07:17,080
To make it super concrete, let's
use that library management 

162
00:07:17,080 --> 00:07:20,280
system example from the source. 
Can you walk us through a 

163
00:07:20,280 --> 00:07:22,320
typical interaction like 
checking out a book? 

164
00:07:22,480 --> 00:07:25,360
Sure thing. 
So imagine the core logic is say

165
00:07:25,360 --> 00:07:28,040
a loan service inside our domain
hexagon. 

166
00:07:28,520 --> 00:07:31,480
OK, a user clicks check out book
on a web page. 

167
00:07:31,640 --> 00:07:34,840
That's the external interface. 
The request hits a web adapter 

168
00:07:34,840 --> 00:07:38,160
living in the outer hexagon. 
This adapter knows web stuff, 

169
00:07:38,360 --> 00:07:40,280
but it doesn't talk directly to 
the loan service. 

170
00:07:40,760 --> 00:07:44,040
Instead it knows about a 
provided port on the domain, 

171
00:07:44,440 --> 00:07:47,560
maybe one that defines A 
checkout book, book head, user 

172
00:07:47,560 --> 00:07:50,000
read operation. 
The web adapter takes the web 

173
00:07:50,000 --> 00:07:53,120
request details and calls that 
checkout book method on the 

174
00:07:53,120 --> 00:07:54,960
port. 
So the web adapter acts like a 

175
00:07:54,960 --> 00:07:57,920
bouncer, taking the web request 
and presenting it cleanly to the

176
00:07:57,920 --> 00:08:00,600
domain via that provided port. 
Exactly. 

177
00:08:00,600 --> 00:08:03,240
Perfect analogy. 
Now the loan service inside the 

178
00:08:03,240 --> 00:08:04,920
domain gets this checkout book 
call. 

179
00:08:04,920 --> 00:08:06,280
It needs to apply business 
rules. 

180
00:08:06,280 --> 00:08:08,400
Is the book actually available? 
Does the user have too many 

181
00:08:08,400 --> 00:08:09,640
books out already? 
Stuff like that. 

182
00:08:09,960 --> 00:08:12,920
To do this it needs data, but it
doesn't know about databases. 

183
00:08:12,920 --> 00:08:15,720
It uses a required port, maybe a
book repository port or user 

184
00:08:15,720 --> 00:08:18,480
repository port. 
This port might define methods 

185
00:08:18,480 --> 00:08:21,360
like find book buyed or get user
account status. 

186
00:08:21,480 --> 00:08:25,800
So the loan service calls say 
find book buyed on its required 

187
00:08:25,800 --> 00:08:29,200
port and SQL database adapter. 
Another adapter in the outer 

188
00:08:29,200 --> 00:08:32,640
ring implements this port. 
It receives the call, translates

189
00:08:32,640 --> 00:08:35,880
find book by into an actual SQL 
query, runs it against the 

190
00:08:35,880 --> 00:08:38,440
database which is outside 
everything, gets the results, 

191
00:08:38,640 --> 00:08:41,000
and sends the book data back to 
the loan service. 

192
00:08:41,240 --> 00:08:44,000
The loan service gets the info 
it needs, completely unaware it 

193
00:08:44,000 --> 00:08:46,440
came via SQL. 
OK, so the domain asks it's 

194
00:08:46,440 --> 00:08:50,000
required port for data and an 
adapter fetches it from the real

195
00:08:50,000 --> 00:08:52,640
database. 
Then, assuming the rules pass 

196
00:08:52,640 --> 00:08:55,080
and the book can be checked out,
the domain needs to record that,

197
00:08:55,080 --> 00:08:56,400
right? 
How does that happen? 

198
00:08:56,400 --> 00:08:58,400
Good. 
Point once the loan service 

199
00:08:58,400 --> 00:09:01,680
decides yes, checkout approved, 
it needs to update the state. 

200
00:09:02,200 --> 00:09:04,840
Maybe mark the book is loaned 
out, update the user's record 

201
00:09:04,840 --> 00:09:06,080
again. 
It doesn't touch the database 

202
00:09:06,080 --> 00:09:08,960
directly, it uses its required 
ports again. 

203
00:09:09,000 --> 00:09:11,120
Book repository port. 
User repository port may be 

204
00:09:11,120 --> 00:09:15,240
calling methods like save book, 
updated book or save user loan, 

205
00:09:15,400 --> 00:09:17,920
loan details. 
The SQL database adapter 

206
00:09:17,920 --> 00:09:20,640
intercepts these calls, 
translates them into SQL you 

207
00:09:20,640 --> 00:09:23,560
date or insert statements and 
executes them against the 

208
00:09:23,560 --> 00:09:25,920
database. 
The change is saved and that 

209
00:09:25,920 --> 00:09:27,760
whole cycle really shows the 
flow. 

210
00:09:28,040 --> 00:09:32,520
External system adapter provided
port domain logic and then 

211
00:09:32,520 --> 00:09:35,880
domain logic required port 
adapter tan with external system

212
00:09:36,440 --> 00:09:39,880
the domain stays clean. 
If tomorrow we want to use a No 

213
00:09:39,880 --> 00:09:42,720
SQL database, we just write a 
new No SQL adapter that 

214
00:09:42,720 --> 00:09:45,080
implements the same required 
repository ports. 

215
00:09:45,560 --> 00:09:47,040
The loan service doesn't change 
at all. 

216
00:09:47,120 --> 00:09:49,880
It really is a robust design. 
You can see the flexibility. 

217
00:09:50,080 --> 00:09:52,480
And Speaking of names, it's 
interesting that Cockburn 

218
00:09:52,480 --> 00:09:55,640
himself later suggested calling 
it Ports and Adapters 

219
00:09:55,640 --> 00:09:57,720
Architecture. 
Wasn't it back in 2005? 

220
00:09:57,720 --> 00:09:59,440
He did, Yeah. 
He apparently had this 

221
00:09:59,440 --> 00:10:02,040
realization, thinking, wait, the
faces of my Hexagon? 

222
00:10:02,040 --> 00:10:04,440
Those are the ports and the 
things connecting to hexagons. 

223
00:10:04,440 --> 00:10:06,960
Those are the adapters. 
He felt Ports and Adapters was 

224
00:10:06,960 --> 00:10:10,080
maybe a more direct, descriptive
name for what's actually going 

225
00:10:10,080 --> 00:10:11,440
on under the hood. 
Makes sense, it's pretty 

226
00:10:11,440 --> 00:10:13,760
literal. 
It is, but you know how things 

227
00:10:13,760 --> 00:10:15,320
go. 
By that time, hexagonal 

228
00:10:15,320 --> 00:10:17,680
architecture had already caught 
on, The visual was strong, and 

229
00:10:17,680 --> 00:10:20,200
it just sort of stuck. 
It's still the name most people 

230
00:10:20,200 --> 00:10:22,760
recognize, even if ports and 
adapters might be slightly more 

231
00:10:22,760 --> 00:10:25,600
explanatory. 
Sometimes the catchy name wins. 

232
00:10:25,760 --> 00:10:28,440
So wrapping this up, what you've
really got with Hexagonal 

233
00:10:28,440 --> 00:10:31,560
architecture, or ports and 
adapters if you prefer, is this 

234
00:10:31,560 --> 00:10:35,920
powerful pattern for getting 
high cohesion, low coupling, and

235
00:10:35,920 --> 00:10:39,360
much better testability. 
It all boils down to that strict

236
00:10:39,360 --> 00:10:41,800
separation in between your core 
business logic, the 

237
00:10:41,800 --> 00:10:45,240
intermexagon, and everything 
external mediated by those ports

238
00:10:45,240 --> 00:10:47,640
and adapters. 
It makes your software flexible,

239
00:10:47,640 --> 00:10:50,280
resilient to change. 
Exactly. 

240
00:10:50,680 --> 00:10:52,800
And if you think about the 
bigger picture, an architecture 

241
00:10:52,800 --> 00:10:56,480
like this really changes how you
approach software longevity. 

242
00:10:56,880 --> 00:10:59,800
You're building systems that are
inherently more adaptable, more 

243
00:10:59,800 --> 00:11:02,800
resilient to the inevitable 
shifts in technology down the 

244
00:11:02,800 --> 00:11:04,440
road. 
It's about building something 

245
00:11:04,440 --> 00:11:07,000
that can truly last. 
Well, thank you for joining us 

246
00:11:07,000 --> 00:11:09,640
on this deep dive today. 
It's been fascinating unpacking 

247
00:11:09,640 --> 00:11:12,360
hexagonal architecture using the
source you provided.