liveBook · Manning

Hexagonal architecture

As explained in Grokking Software Architecture

An architectural pattern that isolates the application core from external systems through ports and adapters.

Imagine testing a server monitor and sending a real text message every time. The business rule is welded to an SMS provider. Hexagonal architecture, also called ports and adapters, protects that rule by putting it inside an application core and treating outside technologies as replaceable connections. section 5.5.1 section 5.11

Think of the core as a clean room, with ports as its airlocks:

  • The core contains business logic and does not depend on databases, user interfaces, or frameworks. section 5.11
  • Ports are interfaces defined by the core. They describe what the application can do or needs, without specifying the technology. section 5.11
  • Adapters translate between ports and outside technologies. An incoming adapter can drive the application; an outgoing adapter can connect it to a service or database. section 5.11 section 5.5.4

The golden rule is that dependencies point inward: outside code knows about the core, not the other way around. Watch for a leaky port that exposes implementation details such as SQL or HTTP types. The hexagon is just a diagram with room for multiple connections—not a requirement to have six ports. section 5.11 section 5.10 section 5.6.2

Swap the alert plug

A server monitor needs to alert an administrator when a server overheats. Instead of creating a Twilio client inside the business logic, the monitor uses an alert port. An SMS adapter can send production alerts, while a console adapter or fake can be used during development and testing. Changing the plug leaves the core logic alone. section 5.5 section 5.5.1 section 5.5.4

Listing 5.8 “After”: Unit Tests
 
 
// 1. The Fake lives OUTSIDE the test method
class FakeAlertPort : IAlertPort 
{ 
    public List<string> SentMessages { get; } = new List<string>(); 
    public void SendAlert(string message) => SentMessages.Add(message); 
}
 
[TestClass] 
public class ServerMonitorTests 
{
    public void ServerOverheating_SendsAlert_ExactlyOnce()
    {        
        // Arrange: Use a simple "Fake" adapter (just a list!)
        var fakePort = new FakeAlertPort(); 
        var monitor = new ServerMonitor(fakePort);
 
       // Act: Poke the core
        monitor.CheckTemperature(100); #A
 
       // Assert: Verify the OUTCOME, not the implementation
        Assert.AreEqual(1, fakePort.SentMessages.Count); #B
        Assert.IsTrue(fakePort.SentMessages[0].Contains("Take cover!"));
    }
}

See a fake alert adapter capture messages so a test can check the monitor’s behavior without sending a real text. section 5.5.4

The extra isolation has a price: ports, adapters, data objects, and mappers add code and can make simple features feel repetitive. A straightforward layered design may be enough for a prototype or thin CRUD application. Consider hexagonal architecture when business rules are rich, multiple interfaces must drive them, or isolated testing matters enough to justify the complexity. section 5.8.1 section 5.8.3 section 5.8.4

How Grokking Software Architecture covers it

How deep it goes
Explains core, ports, adapters, dependency direction, implementation, and tradeoffs with a worked monitoring example.
Examples
Contrasts a Twilio-coupled server monitor with swappable alert adapters and a fake used in a unit test.
What it assumes
Builds on layered architecture and dependency inversion before introducing the core, ports, and adapters.
What you can do after
Apply it to define core-facing ports, connect adapters, and test business logic without external infrastructure.
How it connects
Connects dependency inversion and separation of concerns with layered architecture, clean architecture, and onion architecture.

Also explained in

Compare how 11 books explain hexagonal architecture →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking Software Architecture. The section links point to the parts of the book it draws on.