Building hexagonal architectures on AWS

Furkan Oruc, Dominik Goby, Darius Kunce, and Michal Ploski, Amazon Web Services (AWS)

June 2022 (document history)

This guide describes a mental model and a collection of patterns for developing software architectures. These architectures are easy to maintain, extend, and scale across the organization as product adoption grows. Cloud hyperscalers such as Amazon Web Services (AWS) provide building blocks for small and large enterprises to innovate and create new software products. The rapid pace of these new service and feature introductions leads business stakeholders to expect their development teams to prototype new minimum viable products (MVPs) faster, so that new ideas can be tested and verified as soon as possible. Often, those MVPs are adopted and become part of the enterprise software ecosystem. In the process of producing these MVPs, teams sometimes abandon software development rules and best practices, such as SOLID principles and unit testing. They assume that this approach will speed up development and reduce the time to market. However, if they fail to create a foundational model and a framework for software architecture at all levels, it will be difficult or even impossible to develop new features for the product. Lack of certainty and changing requirements can also slow down the team during the development process.

This guide walks through a proposed software architecture, from a low-level hexagonal architecture to a high-level architectural and organizational decomposition, that uses domain-driven design (DDD) to address these challenges. DDD helps manage business complexity and scale the engineering team as new features are developed. It aligns business and technical stakeholders to the business problems, called domains, by using ubiquitous language. Hexagonal architecture is a technical enabler of this approach in a very specific domain, called a bounded context. A bounded context is a highly cohesive and loosely coupled sub-area of the business problem. We recommend that you adopt hexagonal architecture for all your enterprise software projects regardless of their complexity.

Hexagonal architecture encourages the engineering team to solve the business problem first, whereas classical layered architecture shifts engineering focus away from the domain to solving technical problems first. Furthermore, if software follows a hexagonal architecture, it’s easier to adopt a test-driven development approach, which reduces the feedback loop that developers need to test business requirements. Lastly, using commands and command handlers is a way to apply the single responsibility and open-closed principles from SOLID. Adhering to these principles produces a code base that developers and architects working on the project can easily navigate and understand, and reduces the risk of introducing breaking changes to existing functionality.

This guide is for software architects and developers who are interested in understanding the benefits of adopting hexagonal architecture and DDD for their software development projects. It includes an example of designing an infrastructure for your application on AWS that supports hexagonal architecture. For an example implementation, see Structure a Python project in hexagonal architecture using AWS Lambda on the AWS Prescriptive Guidance website.