Modular Architecture - Hexagonal Demo Project

This project is a sample production-ready implementation for demonstrating the power of Hexagonal Architecture (aka Ports And Adapters Pattern) written in Java.

Table of Contents

• Motivation
• What is the Hexagonal Architecture
• Technologies Used
• What You Will Learn
• Useful Links From Authors
• Useful Links about Hexagonal Architecture
• History
• Contributing
• Code of Conduct
• Authors
• License

Wiki

• How to build and run tests
• How to run acceptance tests at local

Reports

• Sonar Report

Hexagonal Architecture Flow Diagram (click to enlarge)

Motivation

We want to write clean, maintainable, well-defined boundary context, well-tested domain code and isolate business logic from outside concern.

What is the Hexagonal Architecture

The hexagonal architecture was invented by Alistair Cockburn in an attempt to avoid known structural pitfalls in object-oriented software design, such as undesired dependencies between layers and contamination of user interface code with business logic, and published in 2005.

A timeless goal of software engineering has been to separate code that changes frequently from code that is stable.

~ James Coplien / Lean Architecture

We recommend Hexagonal Architecture for those who want to write clean, maintainable, well-defined boundary context, well-tested domain, and decoupling business logic from technical code.

Technologies Used

You can use any programming language for implementing Hexagonal Architecture. Here is the list of technologies we used for the demo application;

• Spring Boot 2
• Java 11
• Gradle 7
• Mono Repo
• Docker
• Mysql
• Redis
• Kafka
• Groovy 3
• Cucumber
• GitHub Actions

It's so easy to reach 100% code coverage if you design by tests wisely via TDD. There are the types of tests written:

• Unit tests
• Dockerized integration tests
• Consumer-driven contract tests
• External verifier contract tests
• Acceptance tests

What You Will Learn

• Implementing two microservices with spring boot
• Designing the APIs with hexagonal architecture
• Packaging by functions and screaming architecture
• How Ports and adapters separate business from integration points
• Writing behavior focused unit tests at domain module
• Writing integration tests isolated from the business at infra module
• Using Gradle to configure microservices and modules
• Using mono-repo to handle all APIs in a single git repository
• Implementing consumer-driven contract tests
• Creating different testing styles for validating data adapters, event consumers/publishers, controllers

Useful Links From Authors

• Modular Architecture for Pragmatic Developers - Slides - Youtube
• Growing Hexagonal Microservices With TDD - Slides, Youtube
• It's Not Solid Anymore: Rethinking Software Design and Modularity - Slides, Youtube

Useful Links about Hexagonal Architecture

• ITT 2018 - Jakub Nabrdalik - Hexagonal Architecture in practice - Youtube
• Ian Cooper on Hexagonal Architectures at Agile Yorkshire - Youtube
• Ports and Adapters Pattern, by Juan Manuel Garrido de Paz - Blog
• DDD, Hexagonal, Onion, Clean, CQRS, … How I put it all together, by Herberto Graca - Blog
• Hexagonal Architecture: three principles and an implementation example, by Erwan Alliaume, Sébastien Roccaserra - Blog

History

This repository is a side project developed while preparing the conference talk "Growing Hexagonal Microservices With TDD" at Java Day Istanbul 2020. As the authors of this repository, we've been using hexagonal architecture in all microservices (i.e. more than 50+ microservices) running in production since 2017. We believe modularity is the key to building maintainable and high-quality software. That's why we shared our demo project with the community to attract their interest in the topic.

Contributing

Please feel free to open tickets to suggest new features and improvement points. Please feel free to contribute.

Code of Conduct

Please take a look at code of conduct before opening issues or creating pull requests.

Authors

• Lemi Orhan Ergin, Software Crafter at Craftgate -> Github, Twitter, Linkedin
• Alican Akkuş, Software Crafter at Craftgate -> Github, Twitter, Linkedin

License

Distributed under the MIT License. See LICENSE for more information.