How to use domain-driven-hexagon: a guide to DDD and hexagonal architecture

What is domain-driven-hexagon?

domain-driven-hexagon is an open-source project by Sairyss, published under the MIT licence. It is a guide rather than a library or framework, so there is nothing to install as a dependency. Its main emphasis is to provide recommendations on how to design software applications, gathered from different sources.

Code examples use NodeJS, TypeScript, the NestJS framework and Slonik for database access. The README says the patterns are framework and language agnostic, so the technologies can be replaced with any alternative.

• Language of examples: TypeScript on NodeJS
• Framework in examples: NestJS
• Database access in examples: Slonik
• Licence: MIT

Should you use this architecture? Read the pros and cons first

The README lists pros including independence from external frameworks and databases, easier testing, built-in security principles, and the ability for different teams to work without stepping on each other's toes. It also notes that new features stay relatively small in effort as the system grows.

The cons are just as important. The README says the architecture requires a firm understanding of SOLID, Clean/Hexagonal Architecture and Domain-Driven Design. It also says the architecture is generally ill-suited to simple CRUD applications because it adds boilerplate, abstractions and up-front complexity.

• Good fit: applications with significant business logic and a team that understands the principles
• Poor fit: small CRUD apps with little business logic

Understand the data flow through the layers

The README's diagram shows how a request moves through the system. A request, CLI command or event is sent to a controller using a plain DTO. The controller maps it to a Command or Query object and passes it to an Application service.

The Application service runs business logic using domain services and entities or aggregates, and reaches the infrastructure layer through ports (interfaces). The infrastructure layer maps data, reads and writes the database, and uses adapters for other I/O. Results travel back up to the controller, which returns data to the user.

• Controller: parses the DTO and maps it to a Command or Query
• Application service: handles the Command or Query and orchestrates logic
• Domain layer: entities, aggregates, value objects and domain services hold business rules
• Infrastructure layer: repositories and adapters talk to databases and external services

Use the guide's building blocks selectively

The README stresses that everything is a recommendation, not a rule. Different projects can have more or fewer layers and building blocks than described. Add more if the application needs them, and skip some if it is not complex enough.

The README suggests analysing how big and complex the application will be, finding a compromise, and using only the layers and building blocks that fit. It says that in real production applications you will most likely need only a fraction of the patterns.

• Start with the sections that match your current problem, such as Entities, Value Objects or Repositories
• Skip patterns that over-complicate a small project

Get the guide onto your machine

The README is meant to be read online, and the project lists no prerequisites. If you want to read it locally, clone the repository with the command below. The source does not describe any other setup steps.

Compare with related projects

The README's own list of related work includes the author's Backend best practices repository, which covers tools and guidelines for backend development. Other projects with overlapping ideas are Clean Architecture examples by Uncle Bob and Explicit Architecture PHP by hgraca.

Choose a companion resource based on what you need: a broader backend checklist, a different language example, or more focus on the Clean Architecture approach.

• Clean Architecture examples by Uncle Bob
• Explicit Architecture PHP by hgraca
• Backend best practices by Sairyss