Hexagonal Architecture

This helps you untangle a messy request — one that comes in through a web page, gets logged, saves data, and sends an email — from a tangled blob into a clear core with four doors. It prepares you for the notes on Ports and Adapters, Dependency Inversion, and Separation of Concerns. It also makes later topics like Domain-Driven Design (structuring software around business rules), Distributed Systems (multiple programs working together across networks), and API Design (standardizing how programs talk to each other) easier to grasp. Without this view, you see only a knot of code. With it, you see the central logic separately from the tools used to reach it.

Imagine you run a small spice shop. You have a counter for customers, a storeroom at the back, and a phone line to suppliers. If you decide to sell online, you do not rebuild the storeroom or change how you talk to suppliers. You add a website. The website talks to the same rules: check the storeroom, take payment, arrange delivery. The storeroom does not care if the request comes from a person at the counter or a web form; it only cares that someone asked for a jar of turmeric.

In software, these core rules are the *domain logic*. The way people reach them — the counter, the website, the phone app — are just different doorways. Each doorway is an *adapter*. The adapter translates the outside world into a format the core understands. Imagine the core is a bank manager reviewing loans. The manager’s rules for approval do not change based on whether the application comes on paper, by phone, or via an app. The manager has a standard form: name, income, debt, job tenure. Any channel that can fill this form works. In code, this standard form is called a *port* — an interface defined by the core that says, 'This is what I need.' The actual paper forms or screen layouts are the *adapters*.

The core never talks to the database or sends emails directly. It asks for these services via ports. The outside world provides adapters to satisfy those requests. Draw the core in the center with connections radiating out, and you have the hexagonal diagram. The point is that you can change any door (database, email service, user interface) without touching the core rules. You can even test the core in a room with no real hardware or network.

Think of a car’s engine and its standard shaft output. The engine produces power through this shaft regardless of whether the car uses a manual gearbox, automatic, or electric motor. The engine does not care about the rest of the car; it only cares about turning the shaft. Similarly, the core defines what it needs (the port), and the outside world provides whatever fits (the adapter). Where the analogy ends: in software, you can update the core code while the system runs, and swap adapters without stopping the engine. Also, a car’s mechanical parts are fixed once built, but software ports are abstract definitions that can evolve as requirements change. The key rule remains: the core defines what is needed; the outside world must obey that definition.

Hexagonal architecture structures software by placing business rules at the center and forcing all external interactions — such as databases, web interfaces, or messaging systems — to go through defined contracts (ports) implemented by interchangeable components (adapters).

This builds on Dependency Inversion (the core defines the interface, so it does not depend on concrete implementations like specific database drivers) and Separation of Concerns (keeping business logic distinct from technical details like HTTP or SQL). It refines layered architecture by using a center-periphery model rather than strict vertical layers. This structure supports maintainability (swapping infrastructure is easy), testability (testing the core without real hardware), and scalability. Neighboring topics include REST and GraphQL (which define specific types of API adapters) and Microservices (where one hexagon might interact with many others across a network).