Ports and Adapters

This unlocks the ability to design AI systems that outlive their infrastructure. When you build a model or an agent that talks to a database today and a different database tomorrow, the port-adapter seam is what lets you swap the database without rewriting the model logic. It is the foundation for Hexagonal Architecture, Dependency Inversion, and the 'ilities' (maintainability, testability, scalability) that make real AI services deployable. Without it, every model you write is welded to one specific tool — and the moment that tool changes, the model does not work anymore.

Think of a power outlet in your wall. The outlet does not care whether you plug in a lamp, a phone charger, or a fan — it only cares that the plug fits the socket. The socket is a port: it defines what the wall will provide (electricity at a certain voltage and shape), and any device that follows that shape can connect. The device itself is an adapter: it takes the raw electricity and translates it into whatever the device needs — light, charge, or air movement. In software, a port is an interface the core (the heart of your AI system) declares: 'I need to store this data,' or 'I need to fetch this user profile.' An adapter is the concrete code that actually does it, for example talking to a specific database like MySQL or Postgres. The core never talks to the database directly; it talks to the port. That way, if you change the database, you only write a new adapter — the core stays untouched.

Imagine you run a restaurant. The kitchen (the core) needs ingredients. It does not care who delivers them, as long as they arrive at the back door in the right containers. The delivery person is an adapter — they take produce from a local farm, a warehouse, or a supermarket and put it into the kitchen's standard crates. If the farm goes out of business, you find a new supplier and give them the same standard crates — the kitchen never changes. The port is the specification of the crates and the delivery schedule; the adapters are the different suppliers. Now where does this analogy break down? In the restaurant, the kitchen also cooks — it produces something new. In a pure port-adapter system, the core only defines what it needs, and the adapter is a passive translator — it does not add business logic. Also, in a real system there can be many ports (the kitchen needs vegetables, meat, and spices, each with its own crate), and many adapters per port (two suppliers for vegetables). The analogy also misses the idea that the port is defined by the core, not by the outside — in the restaurant, the back door standard is set by the kitchen, not by the suppliers.

A port is an interface that the core defines for what it needs from the outside world; an adapter is a concrete implementation of that interface that translates between the core's language and a specific external tool, framework, or service.

This concept is the practical expression of Dependency Inversion, which you have notes on: the interface belongs to the consumer (the core), not the provider (the outside tool). It is also the same idea as Layered Architecture's dependency rule — outer layers may know inner layers, never the reverse — and it is the building block of Hexagonal Architecture, where the core sits at the centre and all external interaction passes through ports and adapters. It directly supports Cohesion and Coupling: high cohesion inside the core, loose coupling between the core and the outside. If you change a database, you write a new adapter — you do not touch the core, which is exactly what Separation of Concerns and Single Responsibility are designed to achieve.