Understanding Hexagonal Architecture: Principles and Implementation Example

Hexagonal Architecture, introduced by Alistair Cockburn in 2005 and revived since 2015, is a software design pattern that isolates the core business logic (the domain) from external concerns such as user interfaces, databases, and other infrastructure.

Three Core Principles

Explicitly separate Application, Domain, and Infrastructure layers.

All dependencies point inward toward the Domain.

Use ports and adapters to isolate the boundaries.

The left side (Application) contains code that interacts with users or external programs, such as console UI, HTTP routes, or JSON serializers. The center (Domain) holds pure business logic and terminology, which should be understandable even by non‑technical domain experts. The right side (Infrastructure) implements technical details like file I/O, database access, or HTTP calls.

Why It Matters

By separating concerns, developers can work on one logical part (application, domain, or infrastructure) without being distracted by the others, leading to clearer code, easier reasoning, and reduced impact of changes. It also enables automated testing of the domain in isolation from external systems.

Implementation Example (C#)

A small console program that prints a poem demonstrates the three layers. The domain reads poems via an IObtainPoems interface, while the console adapter drives the domain through an IRequestVerses interface.

class Program
{
    static void Main(string[] args)
    {
        // 1. Instantiate right‑side adapter ("go outside the hexagon")
        IObtainPoems fileAdapter = new PoetryLibraryFileAdapter(@".\Peoms.txt");
        // 2. Instantiate the hexagon (domain)
        IRequestVerses poetryReader = new PoetryReader(fileAdapter);
        // 3. Instantiate left‑side adapter ("I want ask / go inside")
        var consoleAdapter = new ConsoleAdapter(poetryReader);
        System.Console.WriteLine("Here is some...");
        consoleAdapter.Ask();
        System.Console.WriteLine("Type enter to exit...");
        System.Console.ReadLine();
    }
}

The domain class receives the infrastructure implementation via constructor injection, keeping it dependent only on the abstract IObtainPoems interface:

public PoetryReader(IObtainPoems poetryLibrary)
{
    this.poetryLibrary = poetryLibrary;
}

Running the program produces output such as:

$ ./printPoem
Here is some poem:
I want to sleep
Swat the files
Softly, please.
-- Masaoka Shiki (1867 - 1902)
Type enter to exit...

Testing Benefits

Because the domain depends only on interfaces, it can be unit‑tested with mocks, and integration tests can replace the infrastructure adapter without touching the business logic. This aligns with the SOLID Dependency Inversion Principle and the Interface Segregation Principle.

Further Considerations

Teams should decide how granular ports need to be, how to organise code (prefer business‑oriented modules over type‑based folders), and when the extra abstraction of ports is worthwhile. The pattern is not a silver bullet; for simple projects it may be overkill, while for complex systems it provides a clean separation.

Related architectural styles such as Clean Architecture or CQRS can be explored for deeper isolation or read/write separation.