A red build with nothing wrong in it
The payment-reminder service's nightly test run failed on this:
FAIL reminds by SMS three days before the due date (8.4 s): SmsProviderError 429 Too Many Requests, sandbox limit of 100 messages per day reached
The service reminds customers about unpaid invoices: three days before the due date, by SMS if the customer opted in, by e-mail otherwise, and not at all once the invoice is paid. None of that logic was broken. The test failed because it really sent a text message, through the SMS provider's sandbox, and an earlier branch had used up the day's quota. The same test fails when the provider's sandbox is down, takes eight seconds when it is up, and cannot check the case "the provider rejects the number" without finding a number the provider rejects.
The reason sits in one line of ReminderScheduler, the class with the rules: const sms = new SmsProviderClient(process.env.SMS_API_KEY). The rules create the provider's client themselves, so wherever the rules go, the provider goes too.
The core says what it needs
Hexagonal architecture, also called Ports & Adapters, fixes this by changing who defines the boundary. The application core, the reminder rules, declares in its own terms what it needs from the outside, as an interface it owns. That interface is a port. Code written for one specific technology, which connects the port to that technology, is an adapter. The core depends on no outside technology, so databases, UIs and APIs become plug-ins that can be swapped behind the same port.
For the reminders, the core declares Notifier, with one method, send(reminder), where a reminder holds the customer, the channel, the amount and the due date. Nothing in it mentions HTTP, API keys or the provider's message format. SmsProviderNotifier is the adapter: it implements Notifier, turns a reminder into the provider's request and calls the provider's API. A second adapter, EmailNotifier, implements the same port with the mail service, and a third, ChannelNotifier, also implements Notifier and passes each reminder to the SMS or the e-mail adapter according to its channel.
Look at which way the import now runs. When the program runs, the core calls the SMS adapter. In the source, the adapter imports the port from the core, and the core never imports the adapter. That reversal, at the boundary between the core and the outside, is dependency inversion: the code that changes most (an SMS provider's client) depends on the code that changes least (the rule about three days before the due date), and not the other way round.
Two kinds of port
Notifier is one kind of port, and the reminders need the other kind too. Every night a scheduler starts a run, and the finance team has a "send now" button in its admin page that starts the same run without waiting for the night. Both need a way in.
- A driving port (also called primary or inbound) is how the outside drives the application. Here it is
SendDueReminders, a use case the core implements inReminderScheduler. The nightly job and the admin endpoint are driving adapters: each turns its own trigger, a schedule or an HTTP request, into a call to that port. - A driven port (secondary, or outbound) is something the core needs and calls out to.
Notifieris one;Invoices, which finds the unpaid invoices due in three days, is another. Driven adapters implement them:SmsProviderNotifier,EmailNotifier,SqlInvoices.
The nightly job drives the core through a port the core implements. The core needs a Notifier; the SMS adapter implements it in production, the in-memory one in tests.
Something still has to create the adapters and hand the core its Notifier when the service starts, so that the core can call it without knowing which class it is. That wiring is the subject of Dependency Injection. The core may still be split into layers inside; what it no longer does is depend on the database code beneath it, the cost Layered architecture shows at the bottom of a stack.
The 429 goes away
With the port in place, the test that failed at night no longer touches the provider. It gives the core an InMemoryNotifier, another adapter of a dozen lines that implements Notifier by appending each reminder to a list. The test creates an invoice due on 14 November, runs SendDueReminders as of 11 November, and checks that the list holds one SMS reminder for that customer. It runs in milliseconds and as often as anyone likes. The rejected-number case, which before needed a number the sandbox would reject, takes a second fake whose send throws RecipientRejected, an error the core defines, and the test checks that the core records why that customer was not reminded.
The in-memory adapter has a limit worth stating: it fails only in the ways it was written to fail. The real provider times out, limits its rate, and rejects numbers for reasons nobody predicted, and no in-memory list proves the SMS adapter handles any of that. So the SMS adapter keeps a few tests of its own, run against the provider's sandbox less often, and the core's tests stop paying for them.
When finance later signs with a second SMS provider for customers in one country, the work is one new adapter that implements Notifier and one more rule in ChannelNotifier that hands that country's SMS reminders to it. ReminderScheduler and its tests stay as they are.
Where the boundary leaks
A port only protects the core when it is written in the core's language. Suppose the team had copied the first provider's API into the port: sendSms(to, body, senderId, unicode). Then the core has to pick a sender ID and an encoding in the first provider's terms. A new adapter can absorb a different field name or splitting rule, but if the second provider cannot honour those choices with the same meaning, the port and the core have to change together. When the thing on the other side has a large model of its own that has to be translated, say an accounting system's idea of an invoice, that translation is the job of an Anti-Corruption Layer, sitting in or behind the adapter.
The opposite leak, a core that imports a concrete adapter such as the ORM class, or a domain class that saves itself, reintroduces the dependency the ports exist to invert; Active Record vs Data Mapper covers where persistence logic can live instead, and Repository shows a driven port for loading and saving whole objects.
Each port is also an interface to name and keep, and each use case a little more ceremony. A small service with one database, nothing it would ever swap and tests that already run fast may not earn that cost back. The reminders earned it the night their tests depended on another team's quota.
The reminders on the Hexagonal Architecture Challenge
The Hexagonal Architecture Challenge asks for exactly this boundary. Build the reminders on it: an actor entering through a driving adapter (the finance team through the admin endpoint, say), the SendDueReminders driving port, the core, and two driven ports, Notifier and Invoices, each implemented by a driven adapter. Before you submit, count the adapters your core is connected to directly. However many adapters the diagram holds, that number should be zero.