Lesson 2 · Hexagonal — the shape of a v2 module

Ports & adapters

The single idea the whole architecture turns on — an interface the core owns, and a concrete implementation at the edge that the core never names.

Your win: point at any repository in your services and say which file is the port and which is the adapter, and explain why the arrow between them points the way it does.

Where the name comes from

Alistair Cockburn named "hexagonal architecture" (a.k.a. ports & adapters) to solve one problem: let an application be driven equally by users, other programs, automated tests, or batch scripts — and be "developed and tested in isolation from its eventual run-time devices and databases."¹ The hexagon is just a box with several sides; each side is a port, and each port has one or more adapters plugged into it.

A port is an interface — in your own code

Here is a real port from spike. Notice what it mentions and what it doesn't:

type EmailRepo interface {
    UpsertEmail(ctx context.Context, db database.Ext, e *model.Email) error
    // ... more methods
}

It takes a *model.Email and a database.Ext — and nothing else. No pgx, no SQL, no connection pool. That's the port: a promise about behaviour, stated entirely in the vocabulary of the domain. The command handler (Lesson 6) depends on this.

An adapter is the implementation — at the edge

type EmailRepo struct{}   // the adapter — same name, different package

func (e *EmailRepo) UpsertEmail(ctx context.Context, db database.Ext, ent *model.Email) error {
    // builds an INSERT ... ON CONFLICT string, binds $1,$2,… , calls db.Exec — the pgx lives HERE
}

The adapter is where all the database detail lives — the SQL, the placeholders, the driver. The handler never sees any of it; it only ever holds the interface. Swap this adapter for an in-memory fake in a unit test and the handler can't tell the difference — which is the entire point Cockburn was making.

The arrow: dependency inversion

Why is this more than "use an interface"? Because of which way the dependency points:

Both the core and the adapter depend on the port. The core does not depend on the adapter — it doesn't import the repositories package, doesn't know postgres exists. That inversion (the concrete depends on the abstract, never the reverse) is what makes the database a detail you can replace, mock, or defer.

Same shape, every service

Once you see it in spike, you see it everywhere. conversationmgmt spells the two sides out in the folder names:

conversationmgmt even splits it physically: core/port/ holds every interface, infrastructure/ holds every implementation. The word core is the hexagon's inside; infrastructure is the plugged-in edge. (Whether that boundary actually holds in conversationmgmt is Lesson 4 — hold that thought.)

Check yourself (from memory)

1. Alistair Cockburn, Hexagonal Architecture.

2. In-repo: internal/spike/modules/email/infrastructure/repo_port.go:11, .../repositories/email.go:19, .claude/rules/eureka-v2-conventions.md (storage.go purity).