liveBook · Manning

Adapter

As explained in Grokking Software Architecture

A component in hexagonal architecture that connects a port to an external system or technology.

An adapter is a translator at the edge of a hexagonal architecture. It connects an external technology to a port—the interface through which the application core states what it needs or can do. Like a device plugged into a USB socket, an adapter can be replaced by another that respects the same contract. section 5.11 section 5.3.4

Adapters work on both sides of a conversation:

  • A primary, or driving, adapter receives an outside request and calls a core port. An order controller, for example, translates an HTTP request into a call to the order service. section 5.3.3
  • A secondary, or driven, adapter implements a port the core uses to reach infrastructure. A SQL order repository translates a clean order object into database statements. section 5.3.3

Data can travel outward while dependencies point inward: the database adapter references the core’s interface, not the other way around. This keeps SQL, HTTP, and other technology details outside the business logic. section 5.3.3 section 5.11

One alert port, several plugs

A server monitor asks an IAlertPort to send an alert. A Twilio adapter can send an SMS, a console adapter can display it during development, and a Kafka adapter can publish it. The monitor receives the chosen adapter through its constructor; the application’s entry point wires the pieces together. section 5.5.2

Listing 5.5 “After”: The Scale Adapter (Async Messaging)
public class KafkaAlertAdapter : IAlertPort #A
{
    private readonly IProducer<string, string> _kafkaProducer;
    public KafkaAlertAdapter(IProducer<string, string> kafkaProducer) #B
    { 
        _kafkaProducer = kafkaProducer; 
    }
 
    public void SendAlert(string message)
    {
        var payload = new { Error = message, Timestamp = DateTime.UtcNow }; #C
        var json = JsonSerializer.Serialize(payload); #C
        _kafkaProducer.Produce("server-alerts-topic", json); #D
    }
}

See a driven adapter implement the alert port and translate a message into a Kafka payload. section 5.5.2

Test without the outside world

A fake alert adapter records messages in a list. A test can plug it into the monitor, check an overheating temperature, and verify that one alert was sent—without contacting an external service. section 5.5.4 section 5.11

Keep the boundary useful:

  • Keep ports in the core’s language. A port that exposes SQL types leaks infrastructure details across the boundary. section 5.3.5
  • Keep business rules in the core. A controller or repository packed with those rules becomes a fat adapter rather than a translator. section 5.3.5
  • Weigh flexibility against overhead. Extra interfaces and files make implementations harder to navigate and can be excessive for a simple CRUD application. section 5.8.2 section 5.8.1

For a legacy system, start small: define a port for a new feature or important fix, then build an adapter to the existing database or code. The new boundary can grow without requiring a complete rewrite. section 5.7

How Grokking Software Architecture covers it

How deep it goes
Works through adapter direction, dependency inversion, implementation, wiring, testing, pitfalls, and migration; defers detailed event-driven architecture.
Examples
Illustrates adapters with USB devices, HTTP controllers, SQL repositories, alert services, and a fake alert adapter.
What you can do after
Build adapters from scratch, inject them into a core, and test behavior with a fake implementation.
How it connects
Connects adapters to ports, dependency inversion, dependency injection, anti-corruption layers, and the strangler fig pattern.

Also explained in

Compare how 17 books explain adapter →

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.