liveBook · Manning

Port

As explained in Grokking Software Architecture

A port is an application-facing interface in hexagonal architecture that defines operations used to interact with the application core.

A clean room needs an airlock: supplies can enter without letting the delivery truck drive through the lab. In hexagonal architecture, a port is that airlock—an interface defined by the application core. It states what the core can do or needs, without specifying the outside technology that does the work. section 5.2.3 section 5.11

Ports support two directions of interaction:

  • Primary or driving ports define how the outside world uses the application. An order service might offer PlaceOrder() and CancelOrder(). section 5.3.2
  • Secondary or driven ports define what the application needs from outside. An order repository might offer Save() and FindById(). section 5.3.2

An adapter connects a particular technology to a port. Dependencies point inward: the adapter knows the core’s contract, but the core does not depend on the database, UI, or framework. A different adapter can satisfy the same contract without changing the business logic. section 5.11 section 5.3.4

One alert port, several plugs

A server monitor needs to send an alert, not know how SMS or a console works. Its secondary port, IAlertPort, declares SendAlert(message). The monitor receives an adapter through its constructor; the application’s entry point chooses which adapter to connect. section 5.5.2

Listing 5.6 “After”: The Core (Inside/Domain)
public class ServerMonitor
{
    private readonly IAlertPort _alertPort;
 
    // We "plug in" the adapter via the constructor
    public ServerMonitor(IAlertPort alertPort) #A
    { #A
        _alertPort = alertPort; #A
    } #A
 
    public void CheckTemperature(int temp) #B
    { #B
        if (temp > HIGH_TEMP_THRESHOLD) #B
        { #B
            _alertPort.SendAlert($"Temp is {temp} degrees! Take cover!"); #B
        } #B
    } #B
}

See how the monitor calls the injected port while keeping its temperature rule in the core. section 5.5.2

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!"));
    }
}

A fake adapter records alerts so the monitor can be tested without sending a real message or using the internet. section 5.5.4

Keep the airlock clean. A leaky port exposes outside types, such as SQL or HTTP types, instead of speaking the core’s language. Keep business rules in the core, not in adapters, and design ports around use cases rather than automatically creating one for every database table. section 5.3.5 section 5.10

The payoff is easier substitution and isolated testing, but there is an indirection cost: navigating to an interface may leave you hunting for its implementing adapter. For a legacy system, start small: define a port for one feature, then use an adapter to reach the existing code or database. section 5.8.2 section 5.7

How Grokking Software Architecture covers it

How deep it goes
Explains driving and driven ports, adapter wiring, testing, design pitfalls, and migration; defers detailed external API design.
Examples
Uses order service and repository interfaces, a server alert port with fake adapter, and a crypto portfolio refactoring exercise.
What you can do after
Apply ports to separate core logic from external dependencies and test behavior with fake adapters.
How it connects
Connects ports to hexagonal architecture, adapters, dependency injection, and the composition root.

Also explained in

Compare how 6 books explain port →

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.