---
title: '2020 06 Zvonimir Spajic - Hexagonal Architecture Demystified'
source: 'https://youtube.com/watch?v=ZdlGo9avftU'
video_id: 'ZdlGo9avftU'
date: 2026-06-18
duration_sec: 1684
---

# 2020 06 Zvonimir Spajic - Hexagonal Architecture Demystified

> Source: [2020 06 Zvonimir Spajic - Hexagonal Architecture Demystified](https://youtube.com/watch?v=ZdlGo9avftU)

## Summary

Zvonimir Spajic demystifies hexagonal architecture (also known as Ports and Adapters) by contrasting it with traditional layered architecture. He explains the core concepts of inside/outside, ports, adapters, and dependency inversion, then shows a PHP implementation example and discusses benefits like delayed technical decisions and testability.

### Key Points

- **Origin of Hexagonal Architecture** [02:05] — Hexagonal architecture was introduced by Alistair Cockburn in 2005 as a response to layered architecture. He later suggested the name 'Ports and Adapters' as more descriptive.
- **Layered vs Hexagonal Architecture** [02:47] — In layered architecture, layers are stacked vertically and communication flows downward. In hexagonal architecture, layers wrap around each other like an onion, with communication flowing inward.
- **Inside vs Outside World** [05:03] — The system has two parts: the inside (core application) and the outside (everything else, including database and web client). Adapters translate between outside formats (HTTP, SQL) and inside formats (PHP objects).
- **Ports and Adapters** [07:05] — Ports are interfaces defined by the core. Adapters implement those interfaces to allow different ways of communicating (e.g., HTTP controller, CLI command). The core remains ignorant of how it's called.
- **Driving vs Driven Ports** [11:31] — Driving (primary) ports initiate communication with the core; driven (secondary) ports are called by the core. This distinction helps organize adapters.
- **Dependency Inversion Principle** [18:38] — To avoid violating the inward dependency rule, use dependency inversion: define an interface in the core, and have the concrete implementation in infrastructure depend on that interface.
- **Benefits of Hexagonal Architecture** [20:43] — Benefits include delaying technical decisions (e.g., database choice), easy technology swapping, focus on domain logic, and improved testability by replacing real adapters with test doubles.
- **When to Use Hexagonal Architecture** [26:32] — Use hexagonal architecture when the domain is complex enough that the added complexity pays off through decoupling, testability, and flexibility.

## Transcript

okay so hi everybody I want to talk
about my type of my pock is exactly
teacher demystified so why this world
demystified in the title why should it
be kind of demystified well for me for a
long time hexagonal architecture was
kind of this mystical thing because
whenever I start trying to learn
something about it and there's no
shortage of articles blog posts videos
tutorials conference conferences people
speak about it so there's a lot of
resources but whenever I try to read
something about it I would get over them
pretty fast because all these articles
they often talk about they would start
talking about things like dv/dt d d pd d
c ql c q RS ears comment and comment
past pairs so yeah it was just too much
for me to take and another problem is
all these kind of articles they often
kind of offer a slightly different view
of what hexagonal architecture is so for
me for a while for a long time i was
never quite sure what hexagonal
architecture is it was kind of mystical
for me so my my goal for today is to
kind of do for you what I did for myself
and that is to simplify it or maybe even
the world he still would maybe be a good
choice of word for the title to distill
this kind of clutter about around
hexagonal architecture design in what it
easy like what the original idea of
hexagonal architecture is and then we
can also see how we can kind of expand
it and combine it with all this other
architectural approaches that people
often tend to do so before I start just
a little bit about me my name is Juan
Amir I come from Croatia but I've been
living in Berlin for almost two years
now this is my twitter handle if you if
you wish to follow me on twitter and
yeah i work at a company called made it
love which is budget company but it's a
remote force company so yeah I can I can
barely care where I live alongside
commit Michael Dauphin and I my tests
are s so exact no architecture in 2005
alistair cockburn
published published an article called
hexagonal architecture and then he later
revisited and his
that the name ports and adapters would
be actually a better name for this
architecture he said he believes it's
it's a very description of the intent
behind his architecture but it seems to
me like the name hexagonal kind of
people use it more often I guess it's
just more cool cool name again it is the
same thing those doctors allister's
starts is article by saying it is a
response to the discussion on the
traditional layer architecture so this
is how we got to start our tour by
looking at layered architecture first so
layered architecture states that in
order for us to better to help ourselves
with comprehending and dealing with
software systems the complexity of our
software systems we should divide them
into distinct layers and the difference
between layers is in the level of
abstraction where these layers are going
to result there's no limits to the
number of layers and usually if you look
at depending on the authors you are
you're reading usually there's like
three to four layers and here I'm going
to use a four layered approach as it was
explained in the brew DDD book by Eric
currents so on the top of your stack of
layers you have your user interface
layer so this is the layer where users
talk to your application this is kind of
like the entry point to your application
and also this is the layer way to show
some data types or some data back to the
user you communicate with the used below
this layer you can give your application
layer which orchestrates some domain
objects in your domain layer to perform
some action required by the end user and
the domain layer it contains your domain
objects your business logic is very very
key results and then at the bottom of
this layers stack you have your
infrastructure infrastructure layer is
there just two technical capabilities to
support the upper layers so it's usually
it's more it's about persisting a
messaging right now the way the
communication between this layer goes is
you can only go downwards so layers can
only talk two layers below them and here
you have you can have two approaches one
is the struct approach where a layer can
only talk to the layer that is directly
below within the stack and then there is
like
relaxed approach where a lair can talk
to all the layers that are below in the
stack so in this case the UI layer could
directly talk to the infrastructure
layer instead of going through like
these all these others layers layers so
you don't have to have this kind of
proxy calls between an X now another way
to look at these layers the way that we
traditionally tend to think about them
is to say that their user interface
layer this is the front end of your
application the infrastructure layer
this is the back end and then this
middle part I chose to call the core but
you can also call it may be part of your
software if you wish to be and more 20
now then came Alistar in 2005 and he
proposed a different look at the system
so in our stars is in his view there is
only two distinct parts to a system
there is the inside world and then there
is the outside world the inside world
this is your core this is your
application and everything else is the
ink is the outside world so in this view
the database and the web client are no
longer back into front-end
they're simply outside now as we know
the outside world in this case our
database and our web client they
probably don't talk the same language as
our core budget HP developers so our
core folks HP while our web client talks
HTTP and our database probably some
flavor of SQL so in order for them to
communicate to talk to each other we
need this kind of transformer wrapper to
Solon layer better they're going to
wrapper another hexagon that is wrapping
our core hexagon and in this XML what's
going to happen is people are going to
translate data from the or what the
outside world can understand to the
format that the inside world can
understand so in this case we need to
transform some HTTP requests into some
PHP PHP data structure so a core can
understand and also vice versa if our
core needs to talk to the outside world
it we need to transform this PHP PHP
data structures probably some HP objects
write to some to something that our
outside world can understand in this
case the web client can understand HTTP
responses and
singles with our database we need to
somehow translate data between deserve
my sink relational data and our hp8
structures probably objects and this
transformer wrapper this is where your
adapters are going to live
so this is where reports and afters
coming to place into into plain this in
this page so how does this work let's
say in record you have written use case
may be a registered user action it can
be as simple as some kind of a service
class that accepts some kind of hint
right so you use case using the word use
case here to be a bit more abstract but
technically it can be it can be just a
service class right in reality and this
use case it defines kind of like an
interface right it says if you want to
register user you need to send me as
with this data this is like the
interfaces to the contract for talking
to this your screen stand-in in the
context of doctors architecture this is
the point so your your core is defining
a port of how you can talk to it now as
we already mentioned our web client
cannot directly access this sport
because a web client talks HTTP and our
interface for use case that is that
space free right so what we now need is
an adapter class and we have all written
these kind of adapters a controller
class right so what the controller class
does is it takes the HTTP request
transforms it into some PHP PHP data
data structure again probably object and
sends the passes that they type now in
in this PHP data structure passes it to
abuse case and vice versa if I use case
needs to return some data the controller
class can also transform it to HTTP
response so now suppose that we need to
support another way of talking to our
application another way of kind of
plugging into our use case may be a
silicone mat right maybe we want our
developers to be able to Association to
the server and manually like here the
CLI interface register users or maybe
our clients are kind of factly and they
also want like a CLI command to
do these kind of actions so again we
need an adapter class so we write and
another another adapter now write the
console command adapter which will take
data from CLI input and again transform
it to the same data structure and as it
why your skis now there is an
interesting thing here to note that is
when we needed to add this new way of
talking to our use case talking to our
core we didn't have to touch the code in
our core we only needed to write new
code we only needed to write a new
implementation you adapt you complete
adapt so you see our core is kind of
blissfully ignorant of all the different
ways of talking to all the different
methods talking to the earth to the core
we are going to support so in future if
we are going to maybe support maybe we
were going to have some kind of rabbitmq
then we proper implementer rabbitmq
listener and after that will take data
from the rabbitmq messages trust condom
to PHP objects and pass them to are
useless so you see our core our use case
only cares about interfaces it only
cares about a port and it says as long
as you can plug something that obeys the
sport something the pen talk to this
port
I don't care where this data comes from
so this this kind of architecture has
this kind of as the baked version call
it potential for for timelessness why
because you don't care in the future
they can be many other many other ways
of talking to application your colony on
only cares about the ports so now you
see why
Alistair chose them when he revisited
the article chose the name ports and
adapters to describe this act
architecture so this view we can say
that our system is we can look at the
system as kind of our core that is
surrounded with interfaces to the
outside world and the reason why I also
chose to call it exactly why he chose to
draw a hexagon I was actually quite
simple because it was easier to draw
than a Pentagon and yeah I'm not kidding
he he really stated it but also be the
disguise clean you get the same a notch
with the Pentagon is easier to draw but
you also get this analogy nice visual
analogy where you can say that one edge
of a hexagon represents one way of
talking one reason
application now as I already mentioned
in this blue right picture there's only
the east side role in jobs so it's
already like this very symmetrical image
where the database and the web trying to
move on the back of the front end
they're sitting outside outside so it's
very symmetrical image but in time it is
also a bit of an asymmetrical image so
what I mean by this is that we can still
kind of divide our ports into two
distinct groups ports adapters and the
way we are going to divide them is based
on the way they communicate with the
core so on the left side of this image
and it doesn't have to be on the left
side I just chose to draw it like this
on the left side of the this image we
have our primary ports called the dragon
box and they're called the driving force
because they are the ones who are
initiating the communication with the
core so they are kind of driving their
behavior of our application usually our
web client will say to our jorge do
something for me or give me some data
show something to me right it is it has
this kind of active active role in
communicate in communicating with all
while on the other hand the driven ports
or the secondary port so let's cannibal
as supports when they communicate in the
core it is our it is the core that
initiates communication with them so the
core will tell the database came
give me some data or can persist some
data for me so they have this kind of
more passive passive role in this
communication so that's why they called
the driven or secondary ports so this is
this is a business portal Aptus
Architect reduces hexagonal architecture
Alistair didn't mention any kind of
general instructions on how you should
actually structure your code inside the
poor you didn't say that you can that
you should use layers or and he also
didn't say that you shouldn't use layers
so what about layers right because a lot
of people usually use layers con
combined with examine architecture and a
lot of people will say when you say
example architecture all your layers and
things are talking about layers right
right away
so yeah you can use you can combine
Excel architecture with layers and but
there's a there is a slightly it's like
a subtle difference or maybe not so
subtle between what you gonna have now
with example architecture and layers and
a traditional layered architecture so
again we have our domain domain layer
it's in our core right then we have this
application layer that is kind of
wrapping our our main layer and then the
infrastructure and the user interface
layer there they both live in this kind
of transformer retro as we chose to call
so as you see the difference between
this and traditional layered
architecture is that in traditional
layered architecture we have like a
stack of layers so layers were strike
one on each other while he were here the
layers are kind of like wrapping each
other so it's more like a like like
peeling an onion right like an onion and
actually there is this thing called an
onion architecture and this is very
really similar to that this kind of
formation of onion architecture and
hexagonal architecture and this
difference also means that let me talk
about that communication between layers
as you remember in traditional layered
architecture the communication would go
downwards while it goes inwards right
because layers are wrapping each other
so communication goes from the outside
to the inside to the two towards our
core and this row for communicate about
communication well it only goes inwards
this this applies this applies to
several architectural even if you are
not combining
layers with okay so now that we know
what the exact role of architecture is
let's let's take a look at one example
how we can actually implement it in PHP
this is how I kind of usually go about
it and also it's a combination of what I
saw other people do it in in workshops
and and some tutorials so we're gonna
take a look at the driving side first so
here I have a simple simple let's say
I'm cooking cooking app so we have our
recipes and we have some users if you're
into DDD as you see I kind of have two
bounded contacts here if you don't know
what that means
think of it like this everything related
to a recipe will be in the recipe folder
everything related to user will be in
the user folder so it's kind of like two
soft parts of your application two
modules distinct modules in your
application and I'm gonna have one
hexagon for module one hexagon per
bounded context here
I didn't here I didn't choose to use
layering but I did choose to put my
infrastructure and my UI in different
folders so I I did make distinction
between primary portion and secondary
ports or driving for George and German
ports and then I have my mic or phone so
one way of talking to my application is
going to be bearish a bit so I have this
great controller to create a recipe and
in it on all that my controller does is
it takes some HTTP data from HTTP
request this is kind of simple it's
simply like code and all it is to do is
take this HTTP request take some data
from it and pass transform the data to
some PHP structure and pass it to our to
our core and in our core we have this
create recipe serves it is a very simple
stories Here I am passing just this
string primitive string value probably
want to have something more robust like
a data transfer object or that object or
something like that and keeping it
simple for that for the sake of this
example and what is important here is
not that we want to support another way
of talking to our to our core of
creating a recipe we are another way of
talking to our application we just
implement another adapter and here again
the only difference is that now we take
input from different source but we still
just pass pass data to our to our great
recipe
service that still lives on our core and
we didn't have to do any adjustments to
the code of that lives in our core which
is great recipe service we only added
new code this new in concrete adapt and
again our core really doesn't care if we
are calling this service from from our
CLI command or HTTP control right
it is blissfully ignorant of the ways of
talking to an application you are going
to use so this is only driven on the
driving side let's take a look look at
the driven sir now and it is going to be
a bit more complex but yeah it's it's
but pay attention so on the German side
we have our creators in the core we have
our create recipe service this is our
axle so is that kind of use case winner
so again it's really simple all it does
is it takes this input this string name
of the recipe it creates the recipe
entity and then it persisted by calling
the same method on the dependency that
it has and that is the recipes
repository now if they were paying
attention you realize that we have a bit
of a problem here so we said that the
dependencies are going inwards so as we
see in this image the infrastructure can
talk to the core but the core the core
cannot talk directly to infrastructure
core should be unaware of concrete
infrastructure you are use and if you
look at our code here
our create recipe use case the great
recipe service it is dependent on the
recipes repository it is talking to it
directly because it is a dependency and
the recipes repository it lives in the
infrastructure because it has some
infrastructure related code to actually
persist this end right so this is
problematic because we are we are not
violating this this rule of dependencies
only going in bus so what can we what
can we do about this well we can use
something that is called inversion of
control or people also call it the
pendency version principle and again it
sounds a bit scary but what it actually
means as a rule of thumb what you need
to do is when you have a situation like
this is to introduce an abstraction
usually an interface so what we're going
to do now is we are going to introduce
this interface so now the recipes
repository we're going to introduce an
interface for you and this interface is
going to live in our code because this
is a concept that belongs to our domain
right
saving recipes and patching them this is
a concept that belongs to our court or
domain so now our create recipes service
is dependent on this recipes interface
which lives in the core Andy this is
okay right because they are born in the
core so we are not probably think any
any and dependencies here and our
concrete implementation of this
interface and sqlrepository that will
actually persist this lives in the
and it is also dependent on this
interface but that is also okay because
infrastructure core code can talk to our
core it can be dependent on the code so
we are now not violating any of those
dependencies going inwards rule and this
is what you see it's kind of like called
dependency version because now you see
dependencies are kind of inverse but
yeah that's that's a bit of another
story but this is how it is how you can
kind of treat this trick to not not
violate these dependencies rules and
yeah our sqlrepository now have some SQL
specific code here we are using doctrine
or m to actual persist this persist this
entity so now that we know what our
exceptional architecture is how we can
we know one will be shown one way of
implementing it the question remains is
why should we do it right
are there what are the benefits of
developing your applications this way
well the first big benefit is that it
allows you to delay technical decisions
so why would this be important why would
we want to delay technical decisions
well if you think about it there is a
certain paradox to how we develop
software how we will work on our
projects and that is at the beginning of
our project where a project knowledge is
at the minimum because it's always going
to like with time your project nor with
knowledge is only only going to grow so
at the beginning beginning it's always
at the minimum point and this minimum
point we are making big decisions on the
technical decisions on what technology
we are going to use so wouldn't it be
nice if we could delay these technical
decisions to some point in time where
our project knowledge will be at the
bigger point and then we can make a much
more informed choice of the hold key we
are going to use and hexagonal
architecture allows us to do just this
so for example maybe you are not sure in
your in your project you're starting
your new project maybe you're not sure
do you want to use a sequel database or
a no sequel database so what you can do
is you can help us recipes your
repositories interfaces you introduce
interfaces for your repositories and
then you have this concrete
implementation
interpretations of these repositories
these interfaces and you can implement
them in plain PHP it can be as simple as
they just take your entity they
serialize it and save it to some text
file now this is not something you want
to push the production obviously but it
will work it'll it will work you will be
able to develop your domain play around
with it model it even write test for it
and then when you are when you have some
more knowledge when your lecture more
sure what college you wanna use then
maybe you say okay now I'm going to use
my sequel database at that point all you
need to do is I mean call it look you
need to do only only thing you need to
do easy from any new adapters now
they're gonna really persist to to my
sequel database and then you just plug
those adapters instead of those naive
PHP ones and everything still works
right another thing about this is
exactly architecture allows us to even
when we make these decisions we can
still kind of change our mind
right so we can swap technologies
relatively easy right so say we said
okay we're gonna use my signal and then
for some reason later in the project we
say oh now we want to switch to post
cast on it so again only thing you need
to do is write new adapters and of
course writing your adapters can still
be a lot of work but you don't have to
touch any existing code again you don't
have to touch any code in your core you
don't have to make any adjustments in
your core in your domain only thing your
only thing you need to do is and you
want a new adapters right some
integration tests for them and once
you're sure that is the latter's work
you just plug them in instead of those
my cheap ones and you're good to go
everything still works as no and you can
swap these technologies like do this for
every technology you are use this is my
kind of link has this potential for
timelessness examine architecture
another thing like excitement
I like hexagonal architecture and why I
think it's so popular in the dimension
design community is that it really does
allow you to really focus on the core
and developing your application so your
core your domain can really be domain
driven instead of kind of technology
driven now of course it is maybe a bit
more idealistic to think that you can
really model your core without any
influence from the
infrastructure from the technologies you
are going to use but still it does allow
you to really focus and not not think
about technologies you won't use too
much which is I guess why it's real
popular in the DDD community and another
big thing for about architecture
actually one of the big motivations for
Alistair to kind of start thinking about
it is testability so when it comes to
testability on the drive inside what you
can do is you can replace your real
adapters with test adapters and test
enough actors in this context this is
your your your testing shoot right and
maybe you can have like this nice set of
BDD start s with P head there is where
you can just yeah plug them in and test
your test your use cases test your you
have your acceptance test like this so
you can really test your application in
isolation and you don't have to go test
your application by going through the UI
you can just plug in this test instead
of your UI and and test your code direct
and when it comes to the drill site to
the secondary infrastructure again you
can replace your test infrastructure
with some kind of you can replace your
real our infrastructure is some kind of
test infrastructure sold again let's say
maybe maybe you are talking to some
cloud provider or whatever you can again
create these adapters that will just
needs a kind of PHP implementation but
you will just check if this is calls are
getting true and this is this will help
you because not really tester you can
test your own in isolation and your
tests are going to be much faster
because now you have to test time in the
real infrastructure now don't get me
wrong you will still have your set of
integration tests for your real adapters
but when you are testing your core what
you want to do is you want to test your
business logic inside your core you
don't want to every time you're testing
certain a certain business case in your
core you don't really want want it to
ping the real infrastructure because you
don't we need to retest this integration
with real infrastructure
every time you are testing every single
business case in your domain this is why
you can give this you can switch it with
some testing infrastructure so your
tests are gonna but so your test when
you're testing your core it's work
gonna run much faster and then you have
a separate set of integration tests to
really test your adapters to make sure
that this integration also will work
okay then finally the the final question
to answer is when you actually use
exactly no architecture because some
people I mean one thing that that is
true exactly larger exact architecture
like every architecture course adds a
complexity to your code right and as I
say as every architecture because every
every design pattern they all add some
complexity right and the question for me
here is not not that I should we should
should we add this more complexity but
the question is does it pay off
right because the reason why we have
design patterns and and hire anyone like
higher higher languages is because we as
humans have a problem with grasping the
complexity of a computer right a
computer doesn't really care you can you
can write your application in binary in
machine code right people used to do
that but you cannot write write it now
like a boom your complex application
this is why we can you know these nice
languages and then we get these design
patterns and all that stuff and
architectures to help ourselves to grasp
the complexity of our programs so I
would say that if the if your domain is
compact X enough and you think that you
will gain the benefit of this little
added complexity by using a certain
architectural approach like cell
architecture then I would say you should
use it and it will pay off so the real
question is does it does it pay off and
that was it thank you for your attention
and if you have any questions I believe
we we do have some time for questions