morisono · August 18, 2025 04:57 · Oct 18, 2021 · Oct 14, 2021 · Oct 14, 2021 · Oct 14, 2021
diff --git a/README.md b/README.md
@@ -65,12 +65,13 @@ https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
   * [Ports and Adapters on c2 wiki](http://wiki.c2.com/?PortsAndAdaptersArchitecture)
   * [Hexagonal Architecture on Alistair's webpage](https://alistair.cockburn.us/hexagonal-architecture/)
 
-* ["Hexagonal Architecture in practice"](https://www.youtube.com/watch?v=sOaS83Ir8Ck) and ["Improving your Test Driven Development in 45 minutes"](https://www.youtube.com/watch?v=2vEoL3Irgiw) by Jakyb Nabrdalik
-
+* Talks by Jakub Nabrdalik:
+  * ["Hexagonal Architecture in practice"](https://www.youtube.com/watch?v=sOaS83Ir8Ck)
+  * ["Improving your Test Driven Development in 45 minutes"](https://www.youtube.com/watch?v=2vEoL3Irgiw)
 
 * [Excalidraw Library](https://libraries.excalidraw.com/?target=_excalidraw&referrer=https%3A%2F%2Fexcalidraw.com%2F&useHash=true&token=ggP8dbrNZlW57BKaDFrd5&theme=light&sort=default#corlaez-hexagonal-architecture) used to create the diagrams shown here.
 
 * Implementation examples:
 
-  * [Github Java and Spring](https://github.com/jakubnabrdalik/hentai) by Jakub Nabrdalik (Spring, HTTP API, Repository)
-  * [Replit Java](https://replit.com/@lrn2prgrm/HexagonalArchitectureExample) by me (0 libraries, Console, System Time, Random)
+  * [Github Java Example](https://github.com/jakubnabrdalik/hentai) by Jakub Nabrdalik (Spring, HTTP API, Repository)
+  * [Replit Java Example](https://replit.com/@lrn2prgrm/HexagonalArchitectureExample) by me (0 libraries, Console, System Time, Random)
diff --git a/README.md b/README.md
@@ -40,16 +40,18 @@ Based on talks by Jakub Nabrdalik.
 
 There are multiple ways to implement the ideas of this architecture this is by no means the only one. This implementation is modular and as such it can scale to implement a modular monolith (modulith).
 
-* Each module is in itself following the Hexagonal Architecture.
+* Each module is an Hexagonal Architecture "Hexagon" (It has ports, adapters and use cases).
 * There is a heavy use of package-private and a minimal, thoughtful use of public.
 * Subjects Under Test in your unit tests are Primary adapters (mocking the Primary Port), the DTOs (if needed) and the Primary Port (using fakes and mocking other modules)
 * Each module has a Configuration file that assembles the classes together for production and testing use.
 
 #### Additional notes on implementation
 
-* In the following example I decided to move customerconsole package outside of the customer module because it required it's own module configuration. However there is nothing stopping that package to remain as a folder inside of `com.abc.project.customer`
+* In the following example I decided to move `customerconsole` package outside of the customer module because it required it's own module configuration. However, there is nothing stopping the package to remain as a folder inside of `com.abc.project.customer`
 
-* Depending on the library choice or code implementation, your primary adapters may be required to be public. Jakub's package-private controllers are possible because he uses the Spring framework. Furthermore, primary adapters expose an API to an external agent so you may want to think about it as a public API regardless of the access modifier used for the class.
+* Depending on the library choice or code implementation, your primary adapters may need to be public. Jakub's package-private controllers are possible because he uses the Spring framework.
+
+* Primary adapters expose an API to an external agent so you may want to treat them as a public API regardless of the access modifier used for the class
 
 ![image](https://user-images.githubusercontent.com/18663098/134517033-36c01f32-07f4-4baf-925d-60f0db069211.png)
 

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 ## Hexagonal Architecture
 
-Conceptualized by Alistair Cockburn initially under the name "Ports and Adapters".
+Conceptualized by Alistair Cockburn. Also known as "Ports and Adapters".
 
 In a nutshell:
 

diff --git a/README.md b/README.md
@@ -59,14 +59,16 @@ https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
 ## Useful Links:
 
 * Articles by Alistair Cockburn:
-* * [Hexagonal Architecture on c2 wiki](http://wiki.c2.com/?HexagonalArchitecture)
-* * [Ports and Adapters on c2 wiki](http://wiki.c2.com/?PortsAndAdaptersArchitecture)
-* * [Hexagonal Architecture on Alistair's webpage](https://alistair.cockburn.us/hexagonal-architecture/)
+  * [Hexagonal Architecture on c2 wiki](http://wiki.c2.com/?HexagonalArchitecture)
+  * [Ports and Adapters on c2 wiki](http://wiki.c2.com/?PortsAndAdaptersArchitecture)
+  * [Hexagonal Architecture on Alistair's webpage](https://alistair.cockburn.us/hexagonal-architecture/)
 
 * ["Hexagonal Architecture in practice"](https://www.youtube.com/watch?v=sOaS83Ir8Ck) and ["Improving your Test Driven Development in 45 minutes"](https://www.youtube.com/watch?v=2vEoL3Irgiw) by Jakyb Nabrdalik
 
-* [Github Java Example Implementation](https://github.com/jakubnabrdalik/hentai) by Jakub Nabrdalik (Spring, HTTP API, Repository)
 
-* [Replit Runnable Java Example with Tests](https://replit.com/@lrn2prgrm/HexagonalArchitectureExample) by me (0 libraries, Console, System Time, Random)
+* [Excalidraw Library](https://libraries.excalidraw.com/?target=_excalidraw&referrer=https%3A%2F%2Fexcalidraw.com%2F&useHash=true&token=ggP8dbrNZlW57BKaDFrd5&theme=light&sort=default#corlaez-hexagonal-architecture) used to create the diagrams shown here.
 
-* [Excalidraw Library](https://libraries.excalidraw.com/?target=_excalidraw&referrer=https%3A%2F%2Fexcalidraw.com%2F&useHash=true&token=ggP8dbrNZlW57BKaDFrd5&theme=light&sort=default#corlaez-hexagonal-architecture)  Excalidraw library used to create the diagrams shown here.
+* Implementation examples:
+
+  * [Github Java and Spring](https://github.com/jakubnabrdalik/hentai) by Jakub Nabrdalik (Spring, HTTP API, Repository)
+  * [Replit Java](https://replit.com/@lrn2prgrm/HexagonalArchitectureExample) by me (0 libraries, Console, System Time, Random)
diff --git a/README.md b/README.md
@@ -32,7 +32,7 @@ They deal with with side effects such as: communication outside of the system, r
 
 ## Hexagonal Architecture - Modular Implementation
 
-Based on talks by Jakub Nabrdalik such as https://www.youtube.com/watch?v=2vEoL3Irgiw
+Based on talks by Jakub Nabrdalik.
 
 ![image](https://user-images.githubusercontent.com/18663098/134550566-27227504-0cfd-46d2-8912-aca050056171.png)
 
@@ -63,7 +63,7 @@ https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
 * * [Ports and Adapters on c2 wiki](http://wiki.c2.com/?PortsAndAdaptersArchitecture)
 * * [Hexagonal Architecture on Alistair's webpage](https://alistair.cockburn.us/hexagonal-architecture/)
 
-* [Youtube Talk "Hexagonal Architecture in practice"](https://www.youtube.com/watch?v=sOaS83Ir8Ck) by Jakyb Nabrdalik
+* ["Hexagonal Architecture in practice"](https://www.youtube.com/watch?v=sOaS83Ir8Ck) and ["Improving your Test Driven Development in 45 minutes"](https://www.youtube.com/watch?v=2vEoL3Irgiw) by Jakyb Nabrdalik
 
 * [Github Java Example Implementation](https://github.com/jakubnabrdalik/hentai) by Jakub Nabrdalik (Spring, HTTP API, Repository)
 

diff --git a/README.md b/README.md
@@ -67,6 +67,6 @@ https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
 
 * [Github Java Example Implementation](https://github.com/jakubnabrdalik/hentai) by Jakub Nabrdalik (Spring, HTTP API, Repository)
 
-* [Replit Runnable Java Example with Tests](https://replit.com/@lrn2prgrm/HexagonalArchitectureExample) by me (0 libraries, CLI, System Time, Random)
+* [Replit Runnable Java Example with Tests](https://replit.com/@lrn2prgrm/HexagonalArchitectureExample) by me (0 libraries, Console, System Time, Random)
 
 * [Excalidraw Library](https://libraries.excalidraw.com/?target=_excalidraw&referrer=https%3A%2F%2Fexcalidraw.com%2F&useHash=true&token=ggP8dbrNZlW57BKaDFrd5&theme=light&sort=default#corlaez-hexagonal-architecture)  Excalidraw library used to create the diagrams shown here.
diff --git a/README.md b/README.md
@@ -63,7 +63,7 @@ https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
 * * [Ports and Adapters on c2 wiki](http://wiki.c2.com/?PortsAndAdaptersArchitecture)
 * * [Hexagonal Architecture on Alistair's webpage](https://alistair.cockburn.us/hexagonal-architecture/)
 
-* [Youtube Talk](https://www.youtube.com/watch?v=sOaS83Ir8Ck) by Jakyb Nabrdalik
+* [Youtube Talk "Hexagonal Architecture in practice"](https://www.youtube.com/watch?v=sOaS83Ir8Ck) by Jakyb Nabrdalik
 
 * [Github Java Example Implementation](https://github.com/jakubnabrdalik/hentai) by Jakub Nabrdalik (Spring, HTTP API, Repository)
 

diff --git a/README.md b/README.md
@@ -58,7 +58,10 @@ https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
 
 ## Useful Links:
 
-* Articles by Alistair Cockburn: [Hexagonal Architecture on c2 wiki](http://wiki.c2.com/?HexagonalArchitecture), [Ports and Adapters on c2 wiki](http://wiki.c2.com/?PortsAndAdaptersArchitecture), [Hexagonal Architecture on Alistair's webpage](https://alistair.cockburn.us/hexagonal-architecture/)
+* Articles by Alistair Cockburn:
+* * [Hexagonal Architecture on c2 wiki](http://wiki.c2.com/?HexagonalArchitecture)
+* * [Ports and Adapters on c2 wiki](http://wiki.c2.com/?PortsAndAdaptersArchitecture)
+* * [Hexagonal Architecture on Alistair's webpage](https://alistair.cockburn.us/hexagonal-architecture/)
 
 * [Youtube Talk](https://www.youtube.com/watch?v=sOaS83Ir8Ck) by Jakyb Nabrdalik
 

diff --git a/README.md b/README.md
@@ -58,7 +58,7 @@ https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
 
 ## Useful Links:
 
-* Articles by Alistair Cockburn: [1](http://wiki.c2.com/?HexagonalArchitecture), [2](http://wiki.c2.com/?PortsAndAdaptersArchitecture), [3](https://alistair.cockburn.us/hexagonal-architecture/)
+* Articles by Alistair Cockburn: [Hexagonal Architecture on c2 wiki](http://wiki.c2.com/?HexagonalArchitecture), [Ports and Adapters on c2 wiki](http://wiki.c2.com/?PortsAndAdaptersArchitecture), [Hexagonal Architecture on Alistair's webpage](https://alistair.cockburn.us/hexagonal-architecture/)
 
 * [Youtube Talk](https://www.youtube.com/watch?v=sOaS83Ir8Ck) by Jakyb Nabrdalik
 

diff --git a/README.md b/README.md
@@ -38,7 +38,14 @@ Based on talks by Jakub Nabrdalik such as https://www.youtube.com/watch?v=2vEoL3
 
 ### Modules Project Structure
 
-There are multiple ways to implement the ideas of this architecture this is by no means the only one. This implementation is modular an can scale to implement a modular monolith (modulith).
+There are multiple ways to implement the ideas of this architecture this is by no means the only one. This implementation is modular and as such it can scale to implement a modular monolith (modulith).
+
+* Each module is in itself following the Hexagonal Architecture.
+* There is a heavy use of package-private and a minimal, thoughtful use of public.
+* Subjects Under Test in your unit tests are Primary adapters (mocking the Primary Port), the DTOs (if needed) and the Primary Port (using fakes and mocking other modules)
+* Each module has a Configuration file that assembles the classes together for production and testing use.
+
+#### Additional notes on implementation
 
 * In the following example I decided to move customerconsole package outside of the customer module because it required it's own module configuration. However there is nothing stopping that package to remain as a folder inside of `com.abc.project.customer`
 

diff --git a/README.md b/README.md
@@ -42,7 +42,7 @@ There are multiple ways to implement the ideas of this architecture this is by n
 
 * In the following example I decided to move customerconsole package outside of the customer module because it required it's own module configuration. However there is nothing stopping that package to remain as a folder inside of `com.abc.project.customer`
 
-* Depending on the library choice or code implementation, your primary adapters may be required to be public. Jakub's package-private controllers are possible because he uses the Spring framework. Furthermore, primary adapters apen up an API to an external actor so you may want to think about it as a public API regardless of the access modifier used for the class.
+* Depending on the library choice or code implementation, your primary adapters may be required to be public. Jakub's package-private controllers are possible because he uses the Spring framework. Furthermore, primary adapters expose an API to an external agent so you may want to think about it as a public API regardless of the access modifier used for the class.
 
 ![image](https://user-images.githubusercontent.com/18663098/134517033-36c01f32-07f4-4baf-925d-60f0db069211.png)
 

diff --git a/README.md b/README.md
@@ -40,9 +40,9 @@ Based on talks by Jakub Nabrdalik such as https://www.youtube.com/watch?v=2vEoL3
 
 There are multiple ways to implement the ideas of this architecture this is by no means the only one. This implementation is modular an can scale to implement a modular monolith (modulith).
 
-(*) In the following example I decided to move customerconsole package outside of the customer module because it required it's own module configuration. However there is nothing stopping that package to remain as a folder inside of `com.abc.project.customer`
+* In the following example I decided to move customerconsole package outside of the customer module because it required it's own module configuration. However there is nothing stopping that package to remain as a folder inside of `com.abc.project.customer`
 
-(*) Depending on the library choice or code implementation, your primary adapters may be required to be public. Jakub's package-private controllers are possible because he uses the Spring framework. Furthermore, primary adapters apen up an API to an external actor so you may want to think about it as a public API regardless of the access modifier used for the class.
+* Depending on the library choice or code implementation, your primary adapters may be required to be public. Jakub's package-private controllers are possible because he uses the Spring framework. Furthermore, primary adapters apen up an API to an external actor so you may want to think about it as a public API regardless of the access modifier used for the class.
 
 ![image](https://user-images.githubusercontent.com/18663098/134517033-36c01f32-07f4-4baf-925d-60f0db069211.png)
 

diff --git a/README.md b/README.md
@@ -16,21 +16,20 @@ They define the business rules and they should not depend on code related on how
 
 ### Ports
 
-They expose the ways in which the use cases can be reached (primary) or reach to (secundary) to the outside world. They are technology agnostic.
+They expose the ways in which the use cases can be reached (primary) or reach to (secondary) to the outside world. They are technology agnostic.
 
 ![image](https://user-images.githubusercontent.com/18663098/134550342-54419945-97cc-47c3-89b9-60404bce3e05.png)
 
 ### Adapters
 
-They deal with the code that communicates outside of the system.
+They deal with with side effects such as: communication outside of the system, random generation, current time, etc.
 
 ![image](https://user-images.githubusercontent.com/18663098/134550456-abeb42bf-ad2d-4ee8-b4b4-f084ea5af0e2.png)
 
 ### Port and Adapter Implementation
 
 ![image](https://user-images.githubusercontent.com/18663098/134551536-bde4adc1-bd78-426f-b4d3-a76e132188a4.png)
 
-
 ## Hexagonal Architecture - Modular Implementation
 
 Based on talks by Jakub Nabrdalik such as https://www.youtube.com/watch?v=2vEoL3Irgiw
@@ -39,9 +38,11 @@ Based on talks by Jakub Nabrdalik such as https://www.youtube.com/watch?v=2vEoL3
 
 ### Modules Project Structure
 
-Based on Jakub Nabrdalik's talks About Hexagonal Architecture and TDD.
+There are multiple ways to implement the ideas of this architecture this is by no means the only one. This implementation is modular an can scale to implement a modular monolith (modulith).
+
+(*) In the following example I decided to move customerconsole package outside of the customer module because it required it's own module configuration. However there is nothing stopping that package to remain as a folder inside of `com.abc.project.customer`
 
-(*) In the following example I decided to move customerconsole package outside of the customer module because it required it's own module configuration. However there is nothing stopping that package to remain as a folder inside of `com.abc.project.customer` 
+(*) Depending on the library choice or code implementation, your primary adapters may be required to be public. Jakub's package-private controllers are possible because he uses the Spring framework. Furthermore, primary adapters apen up an API to an external actor so you may want to think about it as a public API regardless of the access modifier used for the class.
 
 ![image](https://user-images.githubusercontent.com/18663098/134517033-36c01f32-07f4-4baf-925d-60f0db069211.png)
 

diff --git a/README.md b/README.md
@@ -54,8 +54,8 @@ https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
 
 * [Youtube Talk](https://www.youtube.com/watch?v=sOaS83Ir8Ck) by Jakyb Nabrdalik
 
-* [Github Java Example Implementation](https://github.com/jakubnabrdalik/hentai) by Jakub Nabrdalik (Spring)
+* [Github Java Example Implementation](https://github.com/jakubnabrdalik/hentai) by Jakub Nabrdalik (Spring, HTTP API, Repository)
 
-* [Replit Runnable Java Example with Tests](https://replit.com/@lrn2prgrm/HexagonalArchitectureExample) by me (0 libraries)
+* [Replit Runnable Java Example with Tests](https://replit.com/@lrn2prgrm/HexagonalArchitectureExample) by me (0 libraries, CLI, System Time, Random)
 
 * [Excalidraw Library](https://libraries.excalidraw.com/?target=_excalidraw&referrer=https%3A%2F%2Fexcalidraw.com%2F&useHash=true&token=ggP8dbrNZlW57BKaDFrd5&theme=light&sort=default#corlaez-hexagonal-architecture)  Excalidraw library used to create the diagrams shown here.
diff --git a/README.md b/README.md
@@ -50,10 +50,12 @@ https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
 
 ## Useful Links:
 
-* https://alistair.cockburn.us/hexagonal-architecture/ by Alistair Cockburn
+* Articles by Alistair Cockburn: [1](http://wiki.c2.com/?HexagonalArchitecture), [2](http://wiki.c2.com/?PortsAndAdaptersArchitecture), [3](https://alistair.cockburn.us/hexagonal-architecture/)
 
-* https://www.youtube.com/watch?v=sOaS83Ir8Ck talk by Jakyb Nabrdalik
+* [Youtube Talk](https://www.youtube.com/watch?v=sOaS83Ir8Ck) by Jakyb Nabrdalik
 
-* https://github.com/jakubnabrdalik/hentai example repo by Jakub Nabrdalik (Spring)
+* [Github Java Example Implementation](https://github.com/jakubnabrdalik/hentai) by Jakub Nabrdalik (Spring)
 
-* https://replit.com/@lrn2prgrm/HexagonalArchitectureExample by me (0 libraries)
+* [Replit Runnable Java Example with Tests](https://replit.com/@lrn2prgrm/HexagonalArchitectureExample) by me (0 libraries)
+
+* [Excalidraw Library](https://libraries.excalidraw.com/?target=_excalidraw&referrer=https%3A%2F%2Fexcalidraw.com%2F&useHash=true&token=ggP8dbrNZlW57BKaDFrd5&theme=light&sort=default#corlaez-hexagonal-architecture)  Excalidraw library used to create the diagrams shown here.
diff --git a/README.md b/README.md
@@ -31,24 +31,24 @@ They deal with the code that communicates outside of the system.
 ![image](https://user-images.githubusercontent.com/18663098/134551536-bde4adc1-bd78-426f-b4d3-a76e132188a4.png)
 
 
-### Modules
+## Hexagonal Architecture - Modular Implementation
 
 Based on talks by Jakub Nabrdalik such as https://www.youtube.com/watch?v=2vEoL3Irgiw
 
 ![image](https://user-images.githubusercontent.com/18663098/134550566-27227504-0cfd-46d2-8912-aca050056171.png)
 
-#### Modules Project Structure
+### Modules Project Structure
 
 Based on Jakub Nabrdalik's talks About Hexagonal Architecture and TDD.
 
 (*) In the following example I decided to move customerconsole package outside of the customer module because it required it's own module configuration. However there is nothing stopping that package to remain as a folder inside of `com.abc.project.customer` 
 
 ![image](https://user-images.githubusercontent.com/18663098/134517033-36c01f32-07f4-4baf-925d-60f0db069211.png)
 
-#### Module configuration and it's relationship with mock testing:
+### Module configuration and it's relationship with mock testing:
 https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
 
-#### Useful Links:
+## Useful Links:
 
 * https://alistair.cockburn.us/hexagonal-architecture/ by Alistair Cockburn
 

diff --git a/README.md b/README.md
@@ -56,4 +56,4 @@ https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
 
 * https://github.com/jakubnabrdalik/hentai example repo by Jakub Nabrdalik (Spring)
 
-* https://replit.com/@lrn2prgrm/ForthrightUniformCustomization#race/Race.java by me (0 libraries)
+* https://replit.com/@lrn2prgrm/HexagonalArchitectureExample by me (0 libraries)
diff --git a/README.md b/README.md
@@ -47,3 +47,13 @@ Based on Jakub Nabrdalik's talks About Hexagonal Architecture and TDD.
 
 #### Module configuration and it's relationship with mock testing:
 https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051
+
+#### Useful Links:
+
+* https://alistair.cockburn.us/hexagonal-architecture/ by Alistair Cockburn
+
+* https://www.youtube.com/watch?v=sOaS83Ir8Ck talk by Jakyb Nabrdalik
+
+* https://github.com/jakubnabrdalik/hentai example repo by Jakub Nabrdalik (Spring)
+
+* https://replit.com/@lrn2prgrm/ForthrightUniformCustomization#race/Race.java by me (0 libraries)
diff --git a/README.md b/README.md
@@ -26,6 +26,11 @@ They deal with the code that communicates outside of the system.
 
 ![image](https://user-images.githubusercontent.com/18663098/134550456-abeb42bf-ad2d-4ee8-b4b4-f084ea5af0e2.png)
 
+### Port and Adapter Implementation
+
+![image](https://user-images.githubusercontent.com/18663098/134551536-bde4adc1-bd78-426f-b4d3-a76e132188a4.png)
+
+
 ### Modules
 
 Based on talks by Jakub Nabrdalik such as https://www.youtube.com/watch?v=2vEoL3Irgiw

diff --git a/README.md b/README.md
@@ -3,7 +3,10 @@
 Conceptualized by Alistair Cockburn initially under the name "Ports and Adapters".
 
 In a nutshell:
+
+```
 Application Driver -> Primary Adapter -> Primary Port -> Use Case -> Secondary Port -> Secondary Adapter -> External System/Side Effect
+```
 
 ![image](https://user-images.githubusercontent.com/18663098/134550249-61ae172a-d1be-45cb-8f2d-c188b68f5e30.png)
 
@@ -30,8 +33,11 @@ Based on talks by Jakub Nabrdalik such as https://www.youtube.com/watch?v=2vEoL3
 ![image](https://user-images.githubusercontent.com/18663098/134550566-27227504-0cfd-46d2-8912-aca050056171.png)
 
 #### Modules Project Structure
+
 Based on Jakub Nabrdalik's talks About Hexagonal Architecture and TDD.
 
+(*) In the following example I decided to move customerconsole package outside of the customer module because it required it's own module configuration. However there is nothing stopping that package to remain as a folder inside of `com.abc.project.customer` 
+
 ![image](https://user-images.githubusercontent.com/18663098/134517033-36c01f32-07f4-4baf-925d-60f0db069211.png)
 
 #### Module configuration and it's relationship with mock testing:

diff --git a/README.md b/README.md
@@ -0,0 +1,38 @@
+## Hexagonal Architecture
+
+Conceptualized by Alistair Cockburn initially under the name "Ports and Adapters".
+
+In a nutshell:
+Application Driver -> Primary Adapter -> Primary Port -> Use Case -> Secondary Port -> Secondary Adapter -> External System/Side Effect
+
+![image](https://user-images.githubusercontent.com/18663098/134550249-61ae172a-d1be-45cb-8f2d-c188b68f5e30.png)
+
+### Use Cases
+
+They define the business rules and they should not depend on code related on how the system communicates with the outside world. Throught the use of Ports and Adapters the Use Cases can be reliably tested and change mainly if the business rules change
+
+### Ports
+
+They expose the ways in which the use cases can be reached (primary) or reach to (secundary) to the outside world. They are technology agnostic.
+
+![image](https://user-images.githubusercontent.com/18663098/134550342-54419945-97cc-47c3-89b9-60404bce3e05.png)
+
+### Adapters
+
+They deal with the code that communicates outside of the system.
+
+![image](https://user-images.githubusercontent.com/18663098/134550456-abeb42bf-ad2d-4ee8-b4b4-f084ea5af0e2.png)
+
+### Modules
+
+Based on talks by Jakub Nabrdalik such as https://www.youtube.com/watch?v=2vEoL3Irgiw
+
+![image](https://user-images.githubusercontent.com/18663098/134550566-27227504-0cfd-46d2-8912-aca050056171.png)
+
+#### Modules Project Structure
+Based on Jakub Nabrdalik's talks About Hexagonal Architecture and TDD.
+
+![image](https://user-images.githubusercontent.com/18663098/134517033-36c01f32-07f4-4baf-925d-60f0db069211.png)
+
+#### Module configuration and it's relationship with mock testing:
+https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051