The Atomic Hexagonal Architecture — on the frontend — with React

Shortname Atomic DDH, with an example on React

Following the Hexagonal Architecture article I published a few years ago on and then the Atomic Design Architecture, this one will showcase a new architecture style that combines both of them with a focus on the frontend with React.

First, let’s remember what is the Hexagonal Architecture.

Hexagonal Architecture

• The Hexagonal Architecture relies on the Layered Architecture, so we have 3 modules : Driver side, Domain and Driven side
• The goal is to isolate the Domain
• We need to apply the Dependency Inversion Principle to inverse the control (IoC), by wiring dependencies thus injecting implementations (Dependency Injection).
• Adapters are implementing Port which are interfaces defined in the Domain module
• The dependency direction is outside inward.
• In therms on Testing, we could tackle with 2 levels : inner layer and outer layer. The outer layer includes the Driver and Driven modules, seen as infrastructure.

The Atomic Design Architecture

However, on the frontend side, we need to consider some specificities, such as as UI components granularity. So I suggested to structure them by relying on the Atomic Design concept as foundation. In fact, the Atomic Design is a methodology to craft design systems, so it does not suggest to be used to structure code or UI implementations.

Atomic Design Components :

• Color as a Token
• A label as Atomic Component
• A Card as Molecule Component
• A List of Card as Organism Component
• A Layout as Template

Atomic Design

The extension with Feature perspective :

• Video Card as Featured Component
• Video Results as Featured Object
• Search Bar as Featured Object
• Tab Bar as Featured Object
• Video Results View : The Search Result View displays the Video cards as a List, but we can add filter or order by options.
• Video Search Page as a Feature Page : Using a template, we display several views on the same page.

Hexagonal Architecture applied to Frontend

One of the best tool that comes with React library is the famous hooks.

Hooks let you use different React features from your components. You can either use the built-in Hooks or combine them to build your own. This page lists all built-in Hooks in React. cf: https://react.dev/reference/react/hooks

So we can build custom hooks to hold some logic as per our need. Let’s see what building blocks we need in order to structure our code with the Hexagonal Architecture.

Building blocks

• SPI Port : it’s within the domain, so we shall use pure typescript, thus defining the port with an interface is the most correct way.
• SPI Adapter : it’s within the infrastructure layer, so we can use frameworks or libraries which we depend on very much. It’s tightly coupled, but it’s ok here. The adapter class must then implement the interface.
• A Context React Element, we can use createContext and useContext, to hold instance of classes, here the use-case class and adapter class. Within the context, we do the dependencies wiring, injecting the adapter into the use-case class, knowing the we define dependency with port inside the use-case class. That is the application of the Dependency Inversion Principle.
• A Module as React Component : we can use it anywhere in the React application, typically we can put it at the root such as in the App or Layout component.
• I intentionally put aside the Driver port/Adapter, as I find them not useful.

With the schema above, we can see that a Feature Module can hold everything that is needed for the feature to run. And it relies on the Custom Context Hook to manage the dependency injection. One things I want to highlight is that the module itself enforce the modularity of the system. It brings flexibility, reusability, isolation, testability and modularity.

In short, it applies the SOLID principles.

Atomic Design Architecture . x . Domain-Driven . x . Hexagonal Architecture

Let’s go further by combining the Hexagonal Architecture with the Atomic Design Architecture. Remember, Atomic Design Architecture is about the modularity and granularity of UI components. So in our case, we just need to know that atoms, molecules, organisms and templates are used inside featured objects, views and pages, but for them to work, we need to declare the context at a higher level.

Now with the schema below, I show how concrete classes/interface/components are mapped to the concept shown above.

You can see the granularity of UI Components, and the mapping of concrete implementation of all concepts in the inner hexagonal and outer hexagonal to represent the flow of interaction starting from user actions.

React Sample

• VideoSearchModule : it wraps the VideoSearchProvider, which holds the Context
• VideoSearchProvider : it wires the dependencies by creating an instance of VideoSearchUsecase and injecting in it the videoSearchAdapter which is the implementation of the VideoSearchPort
• VideoSearchUsecase : implementing the VideoSearchUsecasePort, and holds the domain functions and business rules within it
• VideoSearchAdapter : implementing the VideoSearchPort, and it is in the infrastructure so it is tied to the library and/or framework, and real world constraints.
• VideoSearchPage : it’s the entry point for users to use the feature. It is composed of feature components (objects and views) which is likely having specific behaviour to serve user’s needs.

Search Module and Search Provider

Search Use case and Adapter

Search Page

That’s it.

Wrap up

The combination of Hexagonal and Atomic Design Architecture is very interesting. As I have myself implemented in on a project, and I’m applying to other projects, while encourage my team to do so on entreprise projects. So far, I see clear benefits. The codebase is clean and very well structured. And making change to any part of the application is very easy.

I believe this new architecture style is something new, so I name it Atomic Hexagonal Architecture, but it is also domain driven, referring to DDH (Domain-Driven Hexagonal). Should I name it Atomic DDH Architecture ? I hope you enjoy this article, and that you try to use this on your project.

Cheers!

Reference

• Hexagonal Architecture
• Atomic Design Architecture
• SOLID principles
• Atomic Design
• Reach Hooks

Glossary

• DDD : Domain-Driven Design
• DDH : Domain-Driven Hexagonal