Clean / Hexagonal Architecture

The 30-second version

Every app does two kinds of work. There's domain logicDomain logic (business logic)The rules that make your product what it is — “an order over $100 ships free”, “a refund can't exceed the payment” — as opposed to plumbing like HTTP, SQL or JSON. — "orders over $100 get 10% off", "never sell what's out of stock" — the rules that make the product what it is. And there's plumbing: reading HTTP requests, running SQL, sending email. Clean and hexagonal architecture are both ways to keep those two apart, so you can change one without breaking the other.

In code, the kitchen is your business rules. The waiters and delivery apps are ways in — an HTTP handler, a command-line tool, a background job. The suppliers are things your rules use — a database, an email service. Flip the widget to "code" to see the mapping:

The one rule

If you remember a single thing from this page, make it this: imports point inward. The code for the business rules never imports the HTTP package, the database driver or the email library. Instead, the rules declare what they need ("something that can save an order"), and the outer code provides it. That's called the dependency ruleDependency ruleThe one rule of clean/hexagonal architecture: source code may only import things closer to the center (the business rules). The center imports nothing from the outside..

You may have met the same move at a smaller scale as the "D" in SOLID — dependency inversion. This page applies it to a whole app's structure, which is what people mean by architectureSoftware architectureThe big structural decisions in a system — how it's split into parts, how those parts talk, where data lives. Roughly: the decisions that are expensive to change later..

What this page covers

1. The problem: a checkout handler that does everything (§02), and the rule that fixes it (§03).
2. The vocabulary: ports and adapters, driving and driven (§04), and why hexagonal, onion and Clean are one idea drawn three ways (§05).
3. A full refactor of the checkout in Go and JavaScript — the core (§06), then the adapters and main (§07) — and testing it without a database (§08).
4. Where things go: validation, transactions, data shapes and errors (§09).
5. When it's not worth it (§10), and staff-level topics: enforcing the rule automatically and moving a legacy codebase toward it (§11).
6. Pitfalls (§12), a quiz (§13) and a cheat sheet (§14).

The tangled checkout

Here's the running example for this whole page: a small online shop. A customer sends their email address and a cart — a list of products, each named by its SKUSKU (stock-keeping unit)A shop's short code for one product it sells, e.g. MUG or LAMP. Orders, prices and stock levels all refer to products by their SKU. (a short product code like MUG or LAMP), with a quantity. The shop checks stock, works out the price, saves the order and emails a receipt. The pricing rules are simple:

• 10% off when the items add up to $100 or more.
• Shipping is $5, but free once the order (after discount) reaches $50.
• Never sell more than you have in stock.

The first version

This is how most first versions look — and it works. It's one HTTP handlerHTTP handlerThe code that answers one HTTP request. In Go it's anything with a ServeHTTP(w, r) method (the http.Handler interface): r is the incoming request, w is where you write the response. that does everything, top to bottom. (It's trimmed for space; real ones grow to 200 lines.)

var db *sql.DB // opened in main()

func checkout(w http.ResponseWriter, r *http.Request) {
    var req checkoutRequest // {email, items: [{sku, qty}]}
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, "bad json", 400); return
    }
    tx, _ := db.Begin()
    defer tx.Rollback()
    var subtotal int64 // in cents: 1999 means $19.99
    for _, it := range req.Items {
        var price int64
        err := tx.QueryRow("SELECT price_cents FROM products WHERE sku = $1", it.SKU).Scan(&price)
        if err != nil { http.Error(w, "unknown product", 422); return }
        res, _ := tx.Exec("UPDATE products SET stock = stock - $1 WHERE sku = $2 AND stock >= $1", it.Qty, it.SKU)
        if n, _ := res.RowsAffected(); n == 0 { http.Error(w, it.SKU+" out of stock", 409); return }
        subtotal += price * int64(it.Qty)
    }
    discount := int64(0)
    if subtotal >= 10000 { discount = subtotal / 10 }
    shipping := int64(500)
    if subtotal-discount >= 5000 { shipping = 0 }
    total := subtotal - discount + shipping
    id := rand.Text()
    tx.Exec("INSERT INTO orders (id, email, total_cents) VALUES ($1, $2, $3)", id, req.Email, total)
    tx.Commit()
    smtp.SendMail("mail.example.com:587", nil, "shop@example.com", []string{req.Email}, receipt(id, total))
    w.WriteHeader(201)
    json.NewEncoder(w).Encode(map[string]any{"id": id, "total_cents": total})
}

Look at what the function knows about: the JSON shape of the request, HTTP status codes, table and column names, how transactions work, the pricing rules, the mail server's address. Those are four different jobs, and each one changes for a different reason. Color them in:

1func checkout(w http.ResponseWriter, r *http.Request) {
2    var req checkoutRequest // {email, items: [{sku, qty}]}
3    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
4        http.Error(w, "bad json", 400); return
5    }
6    tx, _ := db.Begin()
7    defer tx.Rollback()
8    var subtotal int64 // in cents: 1999 means $19.99
9    for _, it := range req.Items {
10        var price int64
11        err := tx.QueryRow("SELECT price_cents FROM products WHERE sku = $1", it.SKU).Scan(&price)
12        if err != nil { http.Error(w, "unknown product", 422); return }
13        res, _ := tx.Exec("UPDATE products SET stock = stock - $1 WHERE sku = $2 AND stock >= $1", it.Qty, it.SKU)
14        if n, _ := res.RowsAffected(); n == 0 { http.Error(w, it.SKU+" out of stock", 409); return }
15        subtotal += price * int64(it.Qty)
16    }
17    discount := int64(0)
18    if subtotal >= 10000 { discount = subtotal / 10 }
19    shipping := int64(500)
20    if subtotal-discount >= 5000 { shipping = 0 }
21    total := subtotal - discount + shipping
22    id := rand.Text()
23    tx.Exec("INSERT INTO orders (id, email, total_cents) VALUES ($1, $2, $3)", id, req.Email, total)
24    tx.Commit()
25    smtp.SendMail("mail.example.com:587", nil, "shop@example.com", []string{req.Email}, receipt(id, total))
26    w.WriteHeader(201)
27    json.NewEncoder(w).Encode(map[string]any{"id": id, "total_cents": total})
28}

Four reasons to change, one function

Each change request in the widget lands on the same function, for a different reason. That's what tight couplingCouplingHow much one piece of code has to know about another. Tightly coupled code breaks together; loosely coupled code can change independently. feels like in practice:

• The rules can't run alone. To test "free shipping from $50" you need a database, a mail server and an HTTP request. So people stop writing tests.
• No reuse. The call-centre CLI can't call a function that takes an http.ResponseWriter. So the rules get copied, and the copies drift apart.
• Changes collide. Swapping the database means editing lines inside the pricing loop. Changing the price means scrolling past SQL.
• Bugs hide in the noise. The commit's error and the insert's error are ignored, and the email is sent while the customer waits. In 30 lines of mixed concerns, nobody notices.

The dependency rule

Three rings

Split the checkout into three layersLayerA group of code with one kind of job — e.g. “business rules”, “use cases”, “talking to Postgres”. Layers are stacked or nested, and rules say which layer may use which., drawn as rings:

1. Business rules (center) — prices, discounts, "never sell what's out of stock". We'll put them in a packagePackage / moduleA folder (Go) or file (JS) of code with its own namespace. Other code imports it and can only use what it exports — capitalized names in Go, export in JS. called domain.
2. Use cases — the steps of one thing a user does: "place an order" = load products, price them, take stock, save, send a receipt. Package app.
3. Adapters and frameworks (outside) — the HTTP handler, the Postgres code, the email sender, and main, which plugs them all together. Plus the libraries they use (net/http, database/sql).

Now the rule. Code A has a source-code dependencySource-code dependencyCode A depends on code B when A's file imports B or mentions B's names. If B changes, A may have to change or stop compiling. Different from who calls whom at runtime. on code B when A imports B or mentions B's names — so if B changes, A might have to change too. The dependency rule says those arrows may only point toward the center (or stay inside the outer ring). Switch on the tempting shortcuts and watch:

Why "inward" is the right direction

The inner rings are the things you want to keep stable and the things you most want to test. The outer rings are the things that change for reasons outside your business — a new web framework, a different database, an email vendor that doubled its prices.

When arrows point inward, a change in an outer ring can't break an inner one, because the inner one doesn't know it exists. A pricing test can run without a database, because the pricing code never imports one. That's the whole payoff, in two sentences.

"But the core has to save the order somehow"

Here's the puzzle. When a checkout runs, the use case calls the database code. How can the call go outward while the import goes inward?

The answer is an interfaceInterfaceA list of method names (and their signatures) with no code. Any type that has those methods can be used wherever the interface is expected. In Go this happens automatically, without writing “implements”. owned by the core. Here is the whole trick in three small files:

package app

import "context"

type Order struct {
    ID    string
    Total int64
}

// The port: declared HERE, by the code that uses it.
type Saver interface {
    SaveOrder(ctx context.Context, o Order) error
}

type Checkout struct{ saver Saver }

func NewCheckout(s Saver) *Checkout { return &Checkout{saver: s} }

func (c *Checkout) Place(ctx context.Context, o Order) error {
    // …business rules…
    return c.saver.SaveOrder(ctx, o) // ← the CALL goes out, to whatever was plugged in
}

package postgres

import (
    "context"
    "database/sql"

    "shop/app" // ← the IMPORT points in: SaveOrder below names app.Order
)

type Store struct{ db *sql.DB }

func New(db *sql.DB) *Store { return &Store{db: db} }

// Having this method is all it takes to be an app.Saver.
func (s *Store) SaveOrder(ctx context.Context, o app.Order) error {
    _, err := s.db.ExecContext(ctx, "INSERT INTO orders (id, total_cents) VALUES ($1, $2)", o.ID, o.Total)
    return err
}

checkout := app.NewCheckout(postgres.New(db)) // ← the only line that knows both

Notice why postgres imports app: not to "implement" anything (Go doesn't need that), but because its SaveOrder method names a core type, app.Order. An adapter whose methods only used types from domain would import only domain. Either way the arrow points inward. Watch both directions on the same three boxes:

So, for the same two packages:

• Who calls whom at runtime: app → postgres. (Outward. That's fine.)
• Who imports whom in the source: postgres → app. (Inward. That's the rule.)

That trick — the interface lives with the code that uses it, not the code that implements it — is the dependency inversion principle, and handing the real implementation in from main is dependency injection. Follow the links for more depth; you don't need them for the rest of this page.

The rule in one table

main is special: it's the one place that knows every concrete piece, and wires them together. That's called the composition rootComposition rootThe one place — usually main() — where the program creates all its real dependencies and plugs them into each other. Nowhere else builds them..

Ports and adapters

Hexagonal architectureHexagonal architecture (ports & adapters)A way to structure an app: the business core declares interfaces (“ports”) for everything it needs, and the database, web server and other tools are plugged in as “adapters”. — Alistair Cockburn's name for this idea, also called ports and adapters — gives you the vocabulary for §03's rings. Think of the ports on a laptop: the laptop defines a USB-C port; a charger, a monitor and a keyboard each plug in with their own cable. The laptop doesn't change when you buy a new monitor.

Ports

A portPortAn interface the business core owns that describes one conversation with the outside world, in business words: “save this order”, “send a receipt”, “place an order”. belongs to the core and is phrased in the core's language. For the shop there are three:

• PlaceOrder(email, items) — how the outside world asks the core to do something.
• Store — how the core reads products and saves orders. It says SaveOrder(order), not INSERT INTO.
• Mailer — how the core sends a receipt. It says SendReceipt(order), not "SMTP".

Adapters

An adapterAdapterCode that connects one outside technology to a port: an HTTP handler that calls the core, or a Postgres store that implements the core's storage interface. It translates in both directions. is the code that translates between one technology and one port. The HTTP handler turns a JSON request into a PlaceOrder call and the result back into JSON. The Postgres store turns SaveOrder(order) into SQL. A fake store in a test turns it into "append to a slice".

Two sides: driving and driven

Ports come in two kinds, and the difference matters for who owns what:

• The driving sideDriving side (primary)The things that start work in your app: an HTTP request, a CLI command, a queue message, a test. Their adapters call into the core. (also called primary) starts work: an HTTP request, a CLICLI (command-line interface)A program you run by typing a command in a terminal, e.g. shop place-order --email ana@example.com MUG:2. Another way into the same app, with no web page involved. command, a message from a queue (read by a consumerConsumerA program that receives messages from a broker and does the work they describe — e.g. the service that sends the email.), a test. Its adapters call into the core.
• The driven sideDriven side (secondary)The things your app uses to get work done: the database, the email service, a payment API. The core calls them through interfaces it owns; adapters implement those interfaces. (also called secondary) is what the core uses to get work done: the database, email, a payment API. The core calls them through an interface it owns; the adapters implement that interface.

Notice that on both sides, the adapters depend on the core. Driving adapters import the core so they can call it. Driven adapters import the core types their methods mention — the Postgres store's methods take app.Tx and domain.Order, so it imports app and domain; the email adapter only mentions domain.Order, so it imports only domain. (In Go, implementing an interface needs no import at all, as §03 showed.) The core imports neither.

What a driving port looks like in code

The driving port is the core's public API — in our shop, the PlaceOrder method of a use caseUse case (application service)One thing a user can do with the system, written as a function or method: PlaceOrder, CancelOrder, RefundPayment. It coordinates the domain rules and the ports, step by step. type called app.Checkout. In Go it doesn't have to be a declared interface: a plain method on a structStructGo's way to group named fields into one type, e.g. type User struct { Name string; Age int }. It's like a JS object with a fixed shape. is a fine port. (The HTTP adapter can still declare a one-method interface for its own tests, as §07 shows.) The driven ports are interfaces, because the core needs to accept different implementations — Postgres in production, a fake in tests.

One request, step by step

Here's the PlaceOrder method we'll build in §06, slightly condensed. Step through a checkout for a $120 lamp and two $12 mugs, then the same request when the lamp has sold out:

1func (c *Checkout) PlaceOrder(ctx context.Context, email string, items []Item) (domain.Order, error) {
2    var order domain.Order
3    err := c.store.InTx(ctx, func(tx Tx) error {
4        products, err := tx.Products(ctx, skusOf(items))
5        if err != nil { return err }
6        lines, err := linesFor(items, products)
7        if err != nil { return err }
8        order, err = domain.NewOrder(c.newID(), email, lines)
9        if err != nil { return err }
10        for _, l := range order.Lines {
11            if err := tx.TakeStock(ctx, l.SKU, l.Qty); err != nil { return err }
12        }
13        return tx.SaveOrder(ctx, order)
14    })
15    if err != nil { return domain.Order{}, err }
16    if err := c.mail.SendReceipt(ctx, order); err != nil {
17        c.log.Warn("receipt email failed", "order", order.ID, "err", err)
18    }
19    return order, nil
20}

Hexagonal, onion, Clean: one idea

You'll hear all three names in code reviews and job interviews, sometimes as if they were rivals. They aren't. Each one was drawn by a different person, at a different time, stressing a different part of the same idea:

Onion architectureOnion architectureJeffrey Palermo's 2008 name for the same idea as hexagonal: the app drawn as rings, with the domain model at the center and infrastructure and UI on the outside. and Clean split the inside into more rings; hexagonal keeps just inside and outside. Try placing our packages in each drawing:

What they all react against: the classic layered stack

Before these, the usual picture was a stack: presentation → business → data access → database, each layer calling the one below. It looks tidy, but the business layer imports the data-access layer. So the business rules depend on the database code, and you can't test them — or change databases — without it.

// package orders (business)
import "shop/dal" // ← rules depend on SQL code

func Place(o Order) error {
    if len(o.Items) == 0 { return ErrEmpty }
    return dal.InsertOrder(o)
}

// package app (business) — no SQL import
type Store interface{ SaveOrder(…) error }

// package postgres (data access)
import "shop/app" // ← SQL code depends on rules
func (s *Store) SaveOrder(…) error { … }

That's the single change the three drawings share: flip the arrow between the business code and the data code. Everything else is naming.

Refactor, part 1: the core

Time to rebuild §02's checkout. Here's the layout we're aiming for, in Go and in JavaScript. Every file shown in this section and the next was compiled and run (Go 1.24, Node 22, Postgres 16); §07 also has the small files you need to run it yourself.

shop/                               shop/
  domain/order.go                     src/domain/order.js
  app/checkout.go                     src/app/checkout.js
  adapters/httpapi/handler.go         src/adapters/http.js
  adapters/postgres/store.go          src/adapters/postgres.js
  adapters/email/log.go               src/adapters/log-mailer.js
  cmd/shop/main.go                    src/main.js

The HTTP adapter's Go package is called httpapi, not http, so it doesn't clash with the standard library's net/http, which it imports.

The domain: rules and nothing else

The domain package holds the types and rules of the shop. It imports only errors, fmt and strings. No HTTP, no SQL, no JSON tags.

package domain

import (
    "errors"
    "fmt"
    "strings"
)

// Money is an amount in cents, so 1999 means $19.99. Integers avoid float rounding bugs.
type Money int64

func (m Money) String() string { return fmt.Sprintf("$%d.%02d", m/100, m%100) }

type Product struct {
    SKU   string
    Name  string
    Price Money
}

type Line struct {
    SKU       string
    Qty       int
    UnitPrice Money
}

type Order struct {
    ID                                  string
    Email                               string
    Lines                               []Line
    Subtotal, Discount, Shipping, Total Money
}

// Business errors. Outer layers check for them with errors.Is.
var (
    ErrEmptyCart      = errors.New("cart is empty")
    ErrBadQuantity    = errors.New("quantity must be between 1 and 99")
    ErrBadEmail       = errors.New("email address is not valid")
    ErrUnknownProduct = errors.New("unknown product")
    ErrOutOfStock     = errors.New("out of stock")
)

// NewOrder is the only way to build an Order, so every Order obeys the rules.
func NewOrder(id, email string, lines []Line) (Order, error) {
    if !strings.Contains(email, "@") {
        return Order{}, ErrBadEmail
    }
    if len(lines) == 0 {
        return Order{}, ErrEmptyCart
    }
    var sub Money
    for _, l := range lines {
        if l.Qty < 1 || l.Qty > 99 {
            return Order{}, fmt.Errorf("%s: %w", l.SKU, ErrBadQuantity)
        }
        sub += l.UnitPrice * Money(l.Qty)
    }
    o := Order{ID: id, Email: email, Lines: lines, Subtotal: sub}
    if sub >= 100_00 { // 10% off orders of $100 or more
        o.Discount = sub / 10
    }
    if sub-o.Discount < 50_00 { // shipping is free from $50
        o.Shipping = 5_00
    }
    o.Total = sub - o.Discount + o.Shipping
    return o, nil
}

The rules in NewOrder are exactly §02's rules — but now they're a function you can call with three lines and no database. That's an invariantInvariantA rule that must always hold true about your data — “an account balance is never negative”, “area equals width × height”. Code (and transactions) must keep it true before and after every change. kept in one place: if the only way to build an Order is NewOrder, every order in the system obeys the rules.

The use case: steps and ports

The app package describes one thing a user can do, step by step, and declares the interfaces (driven ports) it needs. It imports domain and nothing from the adapters.

package app

import (
    "context"
    "fmt"
    "log/slog"

    "shop/domain"
)

// ---- Driven ports: what the use case needs from the outside world. ----

// Store runs a piece of work inside one transaction.
type Store interface {
    InTx(ctx context.Context, fn func(tx Tx) error) error
}

// Tx is everything checkout reads and writes, bound to one transaction.
type Tx interface {
    Products(ctx context.Context, skus []string) (map[string]domain.Product, error)
    TakeStock(ctx context.Context, sku string, qty int) error // domain.ErrOutOfStock if too few
    SaveOrder(ctx context.Context, o domain.Order) error
}

type Mailer interface {
    SendReceipt(ctx context.Context, o domain.Order) error
}

// ---- The use case. ----

type Item struct {
    SKU string
    Qty int
}

type Checkout struct {
    store Store
    mail  Mailer
    newID func() string
    log   *slog.Logger
}

func NewCheckout(store Store, mail Mailer, newID func() string, log *slog.Logger) *Checkout {
    return &Checkout{store: store, mail: mail, newID: newID, log: log}
}

func (c *Checkout) PlaceOrder(ctx context.Context, email string, items []Item) (domain.Order, error) {
    var order domain.Order
    err := c.store.InTx(ctx, func(tx Tx) error {
        products, err := tx.Products(ctx, skusOf(items))
        if err != nil {
            return err
        }
        lines, err := linesFor(items, products)
        if err != nil {
            return err
        }
        order, err = domain.NewOrder(c.newID(), email, lines) // ← the rules live in domain
        if err != nil {
            return err
        }
        for _, l := range order.Lines {
            if err := tx.TakeStock(ctx, l.SKU, l.Qty); err != nil {
                return err
            }
        }
        return tx.SaveOrder(ctx, order)
    })
    if err != nil {
        return domain.Order{}, err
    }
    // After the commit: a failed email must not undo a paid order.
    if err := c.mail.SendReceipt(ctx, order); err != nil {
        c.log.Warn("receipt email failed", "order", order.ID, "err", err)
    }
    return order, nil
}

func skusOf(items []Item) []string {
    skus := make([]string, len(items))
    for i, it := range items {
        skus[i] = it.SKU
    }
    return skus
}

// linesFor prices each item from the catalog. An unknown SKU is a business error.
func linesFor(items []Item, products map[string]domain.Product) ([]domain.Line, error) {
    lines := make([]domain.Line, len(items))
    for i, it := range items {
        p, ok := products[it.SKU]
        if !ok {
            return nil, fmt.Errorf("%s: %w", it.SKU, domain.ErrUnknownProduct)
        }
        lines[i] = domain.Line{SKU: it.SKU, Qty: it.Qty, UnitPrice: p.Price}
    }
    return lines, nil
}

Read it as a checklist

Look at what app contains and what it doesn't:

• It owns its ports. Store, Tx and Mailer are declared here, by the code that uses them — so app never needs to import an adapter. (The Postgres adapter will import app, because its InTx method mentions app.Tx; never the reverse.) In Go they match by method set alone (implicit interfacesImplicit interfaceAn interface that a type satisfies just by having the right methods — no “implements” keyword. Go's interfaces all work this way.), so no implements keyword appears anywhere.
• The ports speak business. TakeStock(sku, qty), not Exec("UPDATE …"). A port that mirrored SQL would just be the database's API with an interface in front.
• It decides what happens together, not how. "Load, price, take stock and save as one unit" is a business decision, so the use case asks for InTx. BEGIN/COMMIT is the adapter's problem (§09 has more on this).
• It orders the side effects. The receipt goes out after the commit, so a rollback can never leave a customer with an email for an order that doesn't exist.
• Everything it needs comes in through NewCheckout. That's constructor injection, covered in depth in Dependency Injection.

Refactor, part 2: adapters and main

§06 built the core. Now the outside: one driving adapter (HTTP), two driven adapters (Postgres and email), and main to plug them in.

The HTTP adapter: JSON in, status codes out

package httpapi

import (
    "context"
    "encoding/json"
    "errors"
    "net/http"

    "shop/app"
    "shop/domain"
)

// What this adapter needs from the core. *app.Checkout fits.
type Checkouter interface {
    PlaceOrder(ctx context.Context, email string, items []app.Item) (domain.Order, error)
}

// DTOs: the JSON shapes of this HTTP API. They are not the domain types.
type checkoutRequest struct {
    Email string `json:"email"`
    Items []struct {
        SKU string `json:"sku"`
        Qty *int   `json:"qty"` // a pointer, so "missing" (nil) differs from 0
    } `json:"items"`
}

// formatError checks the request's shape, not business rules. Wrong shape → 400.
func (req checkoutRequest) formatError() string {
    if req.Email == "" {
        return "email is required"
    }
    if req.Items == nil {
        return "items must be an array"
    }
    for _, it := range req.Items {
        if it.SKU == "" || it.Qty == nil {
            return "every item needs a sku and a qty"
        }
    }
    return ""
}

type orderResponse struct {
    ID    string `json:"id"`
    Total string `json:"total"`
}

func Routes(c Checkouter) http.Handler {
    mux := http.NewServeMux()
    mux.HandleFunc("POST /checkout", func(w http.ResponseWriter, r *http.Request) {
        var req checkoutRequest
        if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
            writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid JSON"})
            return
        }
        if msg := req.formatError(); msg != "" {
            writeJSON(w, http.StatusBadRequest, map[string]string{"error": msg})
            return
        }
        items := make([]app.Item, len(req.Items)) // DTO → the core's input type
        for i, it := range req.Items {
            items[i] = app.Item{SKU: it.SKU, Qty: *it.Qty}
        }
        order, err := c.PlaceOrder(r.Context(), req.Email, items)
        if err != nil {
            status := statusFor(err)
            msg := err.Error()
            if status == http.StatusInternalServerError {
                msg = "internal error" // never leak SQL errors to clients
            }
            writeJSON(w, status, map[string]string{"error": msg})
            return
        }
        writeJSON(w, http.StatusCreated, orderResponse{ID: order.ID, Total: order.Total.String()})
    })
    return mux
}

// statusFor translates business errors into HTTP. Only this adapter knows HTTP exists.
func statusFor(err error) int {
    switch {
    case errors.Is(err, domain.ErrEmptyCart),
        errors.Is(err, domain.ErrBadQuantity),
        errors.Is(err, domain.ErrBadEmail),
        errors.Is(err, domain.ErrUnknownProduct):
        return http.StatusUnprocessableEntity // 422
    case errors.Is(err, domain.ErrOutOfStock):
        return http.StatusConflict // 409
    default:
        return http.StatusInternalServerError // 500
    }
}

func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    json.NewEncoder(w).Encode(v)
}

Notice the two kinds of "bad request". formatError asks whether the body has the right shape — an email string, an array of items, each with a SKU and a whole-number quantity. Getting that wrong is the client's mistake in using the API, so it's a 400, decided right here. Whether the quantity is between 1 and 99, or the SKU exists, is a business rule: the adapter passes it to the core, and the core's error becomes a 422. (§09 comes back to this split.)

The request and response structs are DTOsDTO (data transfer object)A plain shape used only to carry data across a boundary — e.g. the JSON body of an HTTP request. It has no rules; it gets converted into domain types at the edge.: they describe the HTTP API's shapes, not the domain's. That's deliberate — §09 explains why the JSON and domain.Order should be free to differ. The error mapping is the other half of the adapter's job: the core says what went wrong in business terms (ErrOutOfStock); the adapter decides what that means in HTTP (HTTP status codeHTTP status codeThe 3-digit number at the start of every HTTP response: 2xx = success (200 OK), 3xx = go elsewhere (301), 4xx = your request was wrong (404 Not Found, 429 Too Many Requests), 5xx = the server failed (500, 503). 409).

The Go adapter depends on a one-method interface it declares itself, Checkouter, rather than on *app.Checkout directly. That's optional; it lets the handler's own tests pass a stub (§08). The driving port is still PlaceOrder — the interface just names it.

The Postgres adapter: SQL and transactions

package postgres

import (
    "context"
    "database/sql"
    "fmt"

    "shop/app"
    "shop/domain"
)

type Store struct{ db *sql.DB }

func New(db *sql.DB) *Store { return &Store{db: db} }

// InTx implements app.Store: BEGIN, run fn, then COMMIT — or ROLLBACK if fn failed.
func (s *Store) InTx(ctx context.Context, fn func(app.Tx) error) error {
    sqlTx, err := s.db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    defer sqlTx.Rollback() // does nothing after a successful Commit
    if err := fn(&tx{sqlTx}); err != nil {
        return err
    }
    return sqlTx.Commit()
}

type tx struct{ q *sql.Tx }

func (t *tx) Products(ctx context.Context, skus []string) (map[string]domain.Product, error) {
    rows, err := t.q.QueryContext(ctx,
        `SELECT sku, name, price_cents FROM products WHERE sku = ANY($1)`, skus)
    if err != nil {
        return nil, err
    }
    defer rows.Close()
    out := map[string]domain.Product{}
    for rows.Next() {
        var p domain.Product
        if err := rows.Scan(&p.SKU, &p.Name, &p.Price); err != nil {
            return nil, err
        }
        out[p.SKU] = p
    }
    return out, rows.Err()
}

func (t *tx) TakeStock(ctx context.Context, sku string, qty int) error {
    res, err := t.q.ExecContext(ctx,
        `UPDATE products SET stock = stock - $1 WHERE sku = $2 AND stock >= $1`, qty, sku)
    if err != nil {
        return err
    }
    if n, _ := res.RowsAffected(); n == 0 {
        return fmt.Errorf("%s: %w", sku, domain.ErrOutOfStock) // SQL result → business error
    }
    return nil
}

func (t *tx) SaveOrder(ctx context.Context, o domain.Order) error {
    _, err := t.q.ExecContext(ctx,
        `INSERT INTO orders (id, email, total_cents) VALUES ($1, $2, $3)`, o.ID, o.Email, o.Total)
    if err != nil {
        return err
    }
    for _, l := range o.Lines {
        _, err := t.q.ExecContext(ctx,
            `INSERT INTO order_lines (order_id, sku, qty, unit_price_cents) VALUES ($1, $2, $3, $4)`,
            o.ID, l.SKU, l.Qty, l.UnitPrice)
        if err != nil {
            return err
        }
    }
    return nil
}

The adapter's job is translation in both directions: domain types become rows (SaveOrder), rows become domain types (Products), and a database fact — "the UPDATE matched zero rows" — becomes a business error the core understands (ErrOutOfStock). The core never sees sql.ErrNoRows, a column name or a rowCount.

The email adapter is the same idea, smaller: a type with a SendReceipt(ctx, order) method. For this demo it just logs; a real one would call SMTP or an email API — and app wouldn't change. Its code, and the other files you need to run the example, are below.

package email

import (
    "context"
    "log/slog"

    "shop/domain"
)

// LogMailer "sends" receipts by logging them. A real SMTP adapter would have the same method.
type LogMailer struct{ Log *slog.Logger }

func (m LogMailer) SendReceipt(ctx context.Context, o domain.Order) error {
    m.Log.Info("receipt sent", "to", o.Email, "order", o.ID, "total", o.Total.String())
    return nil
}

module shop

go 1.24

require github.com/jackc/pgx/v5 v5.7.5

CREATE TABLE products (
  sku         text PRIMARY KEY,
  name        text NOT NULL,
  price_cents bigint NOT NULL,
  stock       int NOT NULL CHECK (stock >= 0)
);
CREATE TABLE orders (
  id          text PRIMARY KEY,
  email       text NOT NULL,
  total_cents bigint NOT NULL
);
CREATE TABLE order_lines (
  order_id         text REFERENCES orders(id),
  sku              text REFERENCES products(sku),
  qty              int NOT NULL,
  unit_price_cents bigint NOT NULL
);
INSERT INTO products VALUES ('MUG', 'Mug', 1200, 10), ('LAMP', 'Lamp', 12000, 1);

main: the one place that knows everything

package main

import (
    "crypto/rand"
    "database/sql"
    "log/slog"
    "net/http"
    "os"

    _ "github.com/jackc/pgx/v5/stdlib" // registers the "pgx" driver

    "shop/adapters/email"
    "shop/adapters/httpapi"
    "shop/adapters/postgres"
    "shop/app"
)

func main() {
    log := slog.New(slog.NewTextHandler(os.Stderr, nil))

    db, err := sql.Open("pgx", os.Getenv("DATABASE_URL"))
    if err != nil {
        log.Error("open db", "err", err)
        os.Exit(1)
    }

    // The composition root: the only place that knows every concrete piece.
    checkout := app.NewCheckout(postgres.New(db), email.LogMailer{Log: log}, rand.Text, log)
    addr := os.Getenv("ADDR") // e.g. ":8080"
    log.Info("listening", "addr", addr)
    if err := http.ListenAndServe(addr, httpapi.Routes(checkout)); err != nil {
        log.Error("server stopped", "err", err)
        os.Exit(1)
    }
}

main is the composition rootComposition rootThe one place — usually main() — where the program creates all its real dependencies and plugs them into each other. Nowhere else builds them.: it builds the real pieces and plugs them in. rand.Text (Go 1.24+) and randomUUID are passed as functions to fill the newID slot. Swapping Postgres for anything else changes one line here, plus a new adapter file — and nothing in domain or app.

Run it

With the three tables created (products, orders, order_lines) and a lamp ($120, 1 in stock) and mugs ($12, 10 in stock) loaded, start the Go server and place three orders:

$ ADDR=:8080 DATABASE_URL=postgres://… go run ./cmd/shop &
$ curl -i -X POST localhost:8080/checkout \
    -d '{"email":"ana@example.com","items":[{"sku":"LAMP","qty":1},{"sku":"MUG","qty":2}]}'
HTTP/1.1 201 Created
Content-Type: application/json

{"id":"TJMIUFSMTBEYEWZUSVGMJSBW5N","total":"$129.60"}

$ curl -i -X POST localhost:8080/checkout -d '{"email":"bo@example.com","items":[{"sku":"LAMP","qty":1}]}'
HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":"LAMP: out of stock"}

$ curl -i -X POST localhost:8080/checkout -d '{"email":"bo@example.com","items":[]}'
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"error":"cart is empty"}

Now the bad inputs. Here is every case run against both servers — Go on port 8080, Node on 8081 — condensed into one table (status code, then the error text from the JSON body):

$ curl -s -w ' %{http_code}\n' -X POST localhost:8080/checkout -d '<body>'    # Go
$ curl -s -w ' %{http_code}\n' -X POST localhost:8081/checkout -d '<body>'    # Node

body                                                    Go                                         Node
{nope                                                   400 invalid JSON                           400 invalid JSON
null                                                    400 email is required                      400 email is required
{"items":[{"sku":"MUG","qty":1}]}                       400 email is required                      400 email is required
{"email":"bo@example.com","items":{"sku":"MUG"}}        400 invalid JSON                           400 items must be an array
{"email":"bo@example.com","items":[null]}               400 every item needs a sku and a qty       400 every item needs a sku and a qty
{"email":"bo@example.com","items":[{"sku":"MUG","qty":"two"}]}
                                                        400 invalid JSON                           400 every item needs a sku and a qty
{"email":"bo@example.com","items":[{"sku":"MUG","qty":0}]}
                                                        422 MUG: quantity must be between 1 and 99 422 (same)
{"email":"bo","items":[{"sku":"MUG","qty":1}]}          422 email address is not valid             422 (same)
{"email":"bo@example.com","items":[{"sku":"TOASTER","qty":1}]}
                                                        422 TOASTER: unknown product               422 (same)

Every status code matches between the two servers; a few 400 messages differ in wording, because Go's JSON decoder rejects wrong types itself ("qty":"two" can't go into an int), while the Node adapter checks them by hand. Shape problems → 400 from the adapter; rule violations → 422 from the core.

The server's log shows the email adapter at work (one line per successful order):

time=2026-10-30T15:35:54.726Z level=INFO msg="receipt sent" to=ana@example.com order=TJMIUFSMTBEYEWZUSVGMJSBW5N total=$129.60

The Node server answers the three good-path requests above with the same status codes and bodies (its IDs are UUIDs). $120 + 2 × $12 = $144; 10% off = $129.60; that's over $50, so shipping is free.

Who knows what

Here's the finished structure, with each package's imports exactly as go list reports them. Notice the arrows: every shop/… import points toward domain.

Testing the core without a database

This is the payoff you were promised in §02. Remember: to test "free shipping from $50" in the tangled handler, you needed Postgres, a mail server and an HTTP request. Now there are two easier layers to test, and neither needs any of that.

Level 1: the domain is just functions

domain.NewOrder takes values and returns values. Testing it needs nothing at all — a table of cases is enough:

func TestNewOrderPricing(t *testing.T) {
    tests := []struct {
        name                      string
        lines                     []Line
        discount, shipping, total Money
    }{
        {"small order pays shipping", []Line{{"MUG", 2, 12_00}}, 0, 5_00, 29_00},
        {"free shipping from $50", []Line{{"MUG", 5, 12_00}}, 0, 0, 60_00},
        {"10% off from $100", []Line{{"LAMP", 1, 120_00}}, 12_00, 0, 108_00},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            o, err := NewOrder("o1", "ana@example.com", tt.lines)
            if err != nil {
                t.Fatal(err)
            }
            if o.Discount != tt.discount || o.Shipping != tt.shipping || o.Total != tt.total {
                t.Errorf("got discount=%v shipping=%v total=%v", o.Discount, o.Shipping, o.Total)
            }
        })
    }
}

Level 2: the use case, with fakes

The use case needs a Store and a Mailer. In the test, we plug in fakesFakeA test double that really works, just in a simpler way — e.g. a store that keeps data in a map instead of a database. Tests check the result, not how it was produced.: simple, working implementations that keep data in memory. The fake store even pretends to have transactions — it works on a copy and only keeps the copy if the function succeeded.

package app_test

// memStore is a fake: a real, working store that keeps everything in maps.
type memStore struct {
    products map[string]domain.Product
    stock    map[string]int
    orders   []domain.Order
}

func (m *memStore) InTx(ctx context.Context, fn func(app.Tx) error) error {
    tx := &memTx{m: m, stock: map[string]int{}}
    for k, v := range m.stock { // work on a copy…
        tx.stock[k] = v
    }
    if err := fn(tx); err != nil {
        return err // …and throw it away on error: that's our "rollback"
    }
    m.stock, m.orders = tx.stock, append(m.orders, tx.saved...) // "commit"
    return nil
}

type memTx struct {
    m     *memStore
    stock map[string]int
    saved []domain.Order
}

func (t *memTx) Products(_ context.Context, skus []string) (map[string]domain.Product, error) {
    out := map[string]domain.Product{}
    for _, s := range skus {
        if p, ok := t.m.products[s]; ok {
            out[s] = p
        }
    }
    return out, nil
}

func (t *memTx) TakeStock(_ context.Context, sku string, qty int) error {
    if t.stock[sku] < qty {
        return domain.ErrOutOfStock
    }
    t.stock[sku] -= qty
    return nil
}

func (t *memTx) SaveOrder(_ context.Context, o domain.Order) error {
    t.saved = append(t.saved, o)
    return nil
}

type fakeMailer struct{ sent []string }

func (f *fakeMailer) SendReceipt(_ context.Context, o domain.Order) error {
    f.sent = append(f.sent, o.Email)
    return nil
}

Now the tests themselves. They set up a shop with 10 mugs and 1 lamp, call PlaceOrder, and check the results — including the case where the second item fails and nothing should have changed:

func newShop() (*memStore, *fakeMailer, *app.Checkout) {
    store := &memStore{
        products: map[string]domain.Product{
            "MUG":  {SKU: "MUG", Name: "Mug", Price: 12_00},
            "LAMP": {SKU: "LAMP", Name: "Lamp", Price: 120_00},
        },
        stock: map[string]int{"MUG": 10, "LAMP": 1},
    }
    mail := &fakeMailer{}
    ids := func() string { return "order-1" }
    return store, mail, app.NewCheckout(store, mail, ids, slog.New(slog.DiscardHandler))
}

func TestCheckoutPlacesOrder(t *testing.T) {
    store, mail, checkout := newShop()

    o, err := checkout.PlaceOrder(context.Background(), "ana@example.com",
        []app.Item{{SKU: "LAMP", Qty: 1}, {SKU: "MUG", Qty: 2}})

    if err != nil {
        t.Fatal(err)
    }
    if o.Total != 129_60 { // $144 - 10% = $129.60, free shipping
        t.Errorf("total = %v, want $129.60", o.Total)
    }
    if store.stock["LAMP"] != 0 || store.stock["MUG"] != 8 {
        t.Errorf("stock = %v", store.stock)
    }
    if len(mail.sent) != 1 {
        t.Errorf("sent %d receipts, want 1", len(mail.sent))
    }
}

func TestCheckoutOutOfStockChangesNothing(t *testing.T) {
    store, mail, checkout := newShop()

    _, err := checkout.PlaceOrder(context.Background(), "ana@example.com",
        []app.Item{{SKU: "MUG", Qty: 2}, {SKU: "LAMP", Qty: 2}}) // only 1 lamp left

    if !errors.Is(err, domain.ErrOutOfStock) {
        t.Fatalf("err = %v, want ErrOutOfStock", err)
    }
    if store.stock["MUG"] != 10 || len(store.orders) != 0 || len(mail.sent) != 0 {
        t.Errorf("a failed checkout changed state: stock=%v orders=%d mails=%d",
            store.stock, len(store.orders), len(mail.sent))
    }
}

What it looks like when you run it

$ go test -v ./app
=== RUN   TestCheckoutPlacesOrder
--- PASS: TestCheckoutPlacesOrder (0.00s)
=== RUN   TestCheckoutOutOfStockChangesNothing
--- PASS: TestCheckoutOutOfStockChangesNothing (0.00s)
PASS
ok      shop/app        0.002s

$ go test ./domain
ok      shop/domain     0.002s

$ node --test --test-reporter=spec
✔ places an order: 10% off, free shipping, stock taken, receipt sent (1.306718ms)
✔ out of stock changes nothing (0.499254ms)
ℹ tests 2
ℹ pass 2
ℹ fail 0
ℹ duration_ms 56.898356

Two milliseconds for the Go package (most of the Node run's 57 ms is starting the test runner). No Docker, no DATABASE_URL, nothing to clean up between tests. How much does that matter? Pick a suite size:

Fakes can lie: keep them honest

A fake is only useful if it behaves like the real thing. What if the fake store forgets to roll back, but Postgres doesn't? Your use case tests would pass, and production would behave differently.

The fix is a contract test: one set of tests that runs against every implementation of a port. Write it once, in a shared package, and call it from the fake's tests and the Postgres adapter's tests:

// Run needs a fresh store holding 10 "MUG"s at $12.00.
func Run(t *testing.T, newStore func() app.Store) {
    ctx := context.Background()

    t.Run("taking too much stock is ErrOutOfStock", func(t *testing.T) {
        err := newStore().InTx(ctx, func(tx app.Tx) error { return tx.TakeStock(ctx, "MUG", 11) })
        if !errors.Is(err, domain.ErrOutOfStock) {
            t.Fatalf("err = %v, want ErrOutOfStock", err)
        }
    })

    t.Run("an error rolls everything back", func(t *testing.T) {
        s := newStore()
        boom := errors.New("boom")
        err := s.InTx(ctx, func(tx app.Tx) error {
            if err := tx.TakeStock(ctx, "MUG", 10); err != nil {
                return err
            }
            return boom // ← fail after taking all the stock
        })
        if !errors.Is(err, boom) {
            t.Fatalf("InTx returned %v, want boom", err)
        }
        err = s.InTx(ctx, func(tx app.Tx) error { return tx.TakeStock(ctx, "MUG", 10) })
        if err != nil {
            t.Fatalf("stock was not restored: %v", err)
        }
    })
}

$ TEST_DATABASE_URL=postgres://… go test -v -run TestPostgresStore ./adapters/postgres
--- PASS: TestPostgresStore (0.01s)
    --- PASS: TestPostgresStore/taking_too_much_stock_is_ErrOutOfStock (0.01s)
    --- PASS: TestPostgresStore/an_error_rolls_everything_back (0.00s)
ok      shop/adapters/postgres  0.019s

The same storetest.Run passes against memStore too. Now the fake and the real store are held to the same promises.

The shape of the test suite

Most of your tests live in the top two rows, so the suite stays fast as the app grows. The real-database tests are still essential — they're the only ones that catch a typo in an SQL string — but you need far fewer of them. These are the integration testsIntegration testA test that runs your code together with real pieces — a real database in Docker, a real HTTP server — to check they work together. Slower than a unit test..

Where things go

The diagram says "rules in the middle, plumbing outside". Real code is messier. Here are the four things teams argue about most, with the answer this page's shop uses and why.

1. Validation: two kinds, two places

"Validate the input" is really two different jobs:

• Is this well-formed? Is the body valid JSON? Is qty a number, not "two"? Is the email field present? These are about the format of one way in, so they belong in the adapter. The HTTP adapter answers them with 400; a CLI adapter would print usage help.
• Is this allowed? Quantity between 1 and 99, at least one item, an email that looks like an address, enough stock. These are business rules. They belong in the domain, so that every way in — HTTP, CLI, a queue consumer — obeys them, and you test them once.

A useful test: if a second adapter would need the same check, it's a business rule and it moves inward.

2. Transactions: the core decides what, the adapter decides how

Checkout touches two tables (stock and orders), and they must change together. Who owns the transaction?

• BEGIN/COMMIT is SQL, so the mechanics belong to the Postgres adapter.
• But which steps must be all-or-nothing is a business decision: "taking stock and saving the order are one step". So the use case must be able to ask for it.

The shop's answer is the Store.InTx(fn) port from §06: the use case says "run these steps together"; the adapter wraps them in a transaction. That's a small unit of workUnit of workA way to run several repository calls as one all-or-nothing step: the core says “do these together”, and the adapter wraps them in one database transaction.. It's also why the Tx port bundles all three operations — products, stock, orders — instead of separate repositoriesRepositoryAn object (usually behind an interface) that loads and saves your domain objects, so the rest of the code never writes SQL for them: Get(id) returns a complete Order; Save(order) stores all of it. In DDD there is one repository per aggregate. that each open their own connection.

// Each call runs on its own; if SaveOrder
// fails, the stock is already gone.
err := c.stock.Take(ctx, "LAMP", 1)
// …
err = c.orders.Save(ctx, order)

// Both inside one transaction: both
// happen, or neither does.
err := c.store.InTx(ctx, func(tx Tx) error {
    if err := tx.TakeStock(ctx, "LAMP", 1); err != nil {
        return err
    }
    return tx.SaveOrder(ctx, order)
})

Two traps to avoid:

• Don't pass *sql.Tx into the core. A Tx parameter of type *sql.Tx puts database/sql in the use case's imports and breaks the rule. The core's Tx is an interface; only the adapter knows it's backed by *sql.Tx.
• Don't do slow or irreversible things inside the transaction. An email can't be rolled back, and an HTTP call to a payment provider holds the transaction (and its row locks) open while you wait. Send after commit, as the shop does — or, if the message must never be lost, write it to an outboxOutbox patternWrite an outgoing event into an outbox table in the same database transaction as the change itself; a separate process reads that table and publishes the events. Either both happen or neither does. table inside the same transaction and send it from a background worker (Message Queues → exactly-once covers how).

Isolation levels, locking and retries are their own subject — see Transactions.

3. DTOs, domain models and rows: three shapes, on purpose

The same order exists in three shapes in our shop:

Keeping them separate means each can change on its own schedule. You can rename a column without breaking API clients, or add a field to the domain without exposing it in JSON. The cost is mappingMappingCopying data from one shape to another at a boundary: JSON request → domain input, domain order → database row, domain error → HTTP status code. code — the small loops that copy one shape into another, like the items loop in the HTTP handler.

4. Errors: the core names them, each adapter translates them

The core reports problems in business words: ErrOutOfStock, ErrEmptyCart. It never mentions status codes. Each driving adapter translates:

• The HTTP adapter maps ErrOutOfStock → 409 Conflict, the validation errors → 422, anything else → 500 (and hides the message, so SQL errors don't leak to clients).
• A CLI adapter would map the same errors to an exit code and a message on stderr.

Driven adapters translate in the other direction: the Postgres adapter turns "0 rows updated" into ErrOutOfStock, so the core never has to recognise a database-specific result. Every translation happens at an edge, which keeps the core readable and each adapter replaceable. How to design the error bodies of a public API is covered in API Design.

Practice

Costs, and when it's overkill

Everything so far made the checkout better. But count the files: §02's one function became six files, four interfaces and two sets of mapping code. For checkout, with real rules and two ways in, that's a good trade. For many other parts of an app, it isn't.

What it costs

• Mapping boilerplate. DTO → input → domain → row, and back. When the shapes are identical — a "product" form that saves a "product" row — the mapping is pure copying, and every new field must be added in four places.
• Indirection. "Go to definition" on c.store.InTx lands on an interface, not code. New teammates have to learn where the real thing lives.
• Interfaces with one implementation. An interface you never fake and never swap is just a second place to update when a method changes. Building it "in case we need it" goes against YAGNIYAGNI“You Aren't Gonna Need It”: don't build features or flexibility until a real need shows up. Predicted needs are usually wrong..
• More decisions. Every new function prompts "which layer?". In a small app, that discussion costs more than it saves.

When it's overkill

A CRUDCRUDCreate, Read, Update, Delete: an app that mostly stores forms in tables and shows them back, with few business rules in between. screen — an admin page that lists, edits and deletes products — has no rules to protect. Its "domain" would be a struct identical to the row and the JSON, and its "use case" would be one line that calls the repository. Wrapping that in ports and adapters adds files and protects nothing. The same goes for prototypes, one-off scripts and anything with a lifespan of weeks.

The usual sign you've gone too far is an anemic domain modelAnemic domain modelDomain types that are only data (fields with getters and setters) while all the rules live in separate “service” functions. The name, from Martin Fowler, is critical: the rules can be bypassed by anyone who sets a field.: a domain package full of structs with no behavior, a service layer that only forwards calls, and a repository that only forwards those. Three layers, zero rules.

Screaming architecture: name folders after the business

Robert Martin's screaming architectureScreaming architectureRobert Martin's idea that a project's top-level folders should “scream” what the app does (orders/, payments/, catalog/), not which framework it uses (controllers/, models/). idea: open the project, and the top-level folders should "scream" what the app does — checkout/, catalog/, payments/ — not which framework it uses — controllers/, models/, services/.

Our layout from §06 (domain/, app/, adapters/) is fine for one feature. With twenty features, it becomes a domain/ folder holding twenty unrelated files, and every change touches three distant folders. The fix is package by featurePackage by featureGrouping code by what it does for the business (orders, payments) instead of by technical kind (handlers, models, repositories). Each feature package holds its own layers. — each feature gets its own core, and the adapters sit next to it:

shop/
  domain/    order.go product.go refund.go user.go …
  app/       checkout.go refund.go signup.go …
  adapters/
    httpapi/   checkout.go refund.go signup.go …
    postgres/  orders.go products.go users.go …

shop/
  checkout/              ← core: rules + use case + ports
    postgres/            ← its driven adapter
    httpapi/             ← its driving adapter
  catalog/               ← plain CRUD: handlers + SQL, no layers
  refunds/
  cmd/shop/main.go

The dependency rule still holds inside each feature: checkout/postgres imports checkout, never the reverse. And each feature can choose its own amount of structure — catalog stays simple.

Go-specific advice

Go's design pushes against some habits imported from Java-style Clean Architecture. Lean into it:

• Packages by feature, named for what they provide. checkout, not services. Go package names appear at every call site (checkout.NewService), so they should read well. See Package design and naming.
• Small interfaces, declared by the consumer. One to three methods, in the package that calls them — exactly what app.Tx and httpapi.Checkouter are. See Accept interfaces, return structs.
• Don't create an interface until a second implementation exists. A test fake counts as the second one. If you never fake the logger, take the concrete *slog.Logger, as our Checkout does.
• No interface in front of pure code. domain.NewOrder is a plain function; nobody needs to swap it, so nobody needs a Pricer interface.
• Avoid a shared interfaces or models package. Everything ends up importing it, and it becomes a god packageGod objectOne class, struct or module that knows and does far too much — login, billing, emails, reports — so almost every change has to go through it. that couples features to each other.

In JavaScript the same advice applies with less friction, since Duck typingDuck typing“If it walks like a duck and quacks like a duck, it's a duck”: code accepts any object that has the methods it calls, without checking its class. This is how plain JavaScript works. means a fake never needs a declared interface. The trap there is the opposite one: with no compiler checks, nothing stops app/checkout.js from importing pg. §11 shows how to add that check.

More on spotting over-engineering in general: Anti-patterns → Premature abstraction and SOLID → When SOLID becomes over-engineering.

Enforcing boundaries and evolving legacy code

Why rules erode

Nobody breaks the dependency rule on purpose. Someone needs the request's user ID deep in the pricing code, and importing net/http is the fastest way to get it. The review is busy; it merges. Six months later the domain imports four infrastructure packages and its tests need Docker. A boundary that isn't checked by a machine isn't a boundary.

The fix is an architecture testArchitecture testAn automated check — a test, linter rule or CI step — that fails when code breaks a structural rule, such as “domain must not import database/sql”.: an automated check, run in CICI (continuous integration)A server that builds your code and runs its tests automatically on every push (GitHub Actions, GitLab CI, …), so mistakes are caught minutes after they're made. A flaky test there blocks everyone's merges. on every change, that encodes "which package may import which".

Go: a 30-line test with go list

go list prints every package and its imports. A normal Go test can run it and check the result:

package shop_test

import (
    "os/exec"
    "strings"
    "testing"
)

// Inner layers may not import outer ones. key = layer, value = forbidden prefixes.
var forbidden = map[string][]string{
    "shop/domain": {"shop/app", "shop/adapters", "database/sql", "net/http"},
    "shop/app":    {"shop/adapters", "database/sql", "net/http"},
}

func TestDependencyRule(t *testing.T) {
    out, err := exec.Command("go", "list", "-f", `{{.ImportPath}} {{join .Imports " "}}`, "./...").Output()
    if err != nil {
        t.Fatal(err)
    }
    for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
        pkg, imports, _ := strings.Cut(line, " ")
        for _, imp := range strings.Fields(imports) {
            for _, bad := range forbidden[pkg] {
                if strings.HasPrefix(imp, bad) {
                    t.Errorf("%s imports %s: inner layers must not depend on outer ones", pkg, imp)
                }
            }
        }
    }
}

Now someone adds net/http to the domain "so errors can carry a status code":

$ go test -run DependencyRule .
--- FAIL: TestDependencyRule (0.09s)
    arch_test.go:25: shop/domain imports net/http: inner layers must not depend on outer ones
FAIL

And if someone makes app import the Postgres adapter, Go itself refuses before the test even runs, because postgres already imports app:

$ go build ./...
package shop/adapters/httpapi
	imports shop/app from handler.go
	imports shop/adapters/postgres from checkout.go
	imports shop/app from store.go: import cycle not allowed

Go has one more built-in tool: a directory named internal. Packages under checkout/internal/… can be imported only by code inside checkout/. Use it to keep other features from reaching into a feature's private pieces — the compiler enforces it, no test needed. For bigger codebases, linters such as depguard (part of golangci-lint) express the same rules as configuration.

JavaScript: ESLint and dependency-cruiser

ESLint's built-in no-restricted-imports rule can forbid imports per folder (ESLint 9+ "flat config", checked here with ESLint 10.14):

export default [
  {
    files: ["src/domain/**/*.js"],
    rules: {
      "no-restricted-imports": ["error", {
        patterns: [{ group: ["**/app/**", "**/adapters/**", "pg", "node:http"],
                     message: "domain is the core: it may not import outer layers or infrastructure." }],
      }],
    },
  },
  {
    files: ["src/app/**/*.js"],
    rules: {
      "no-restricted-imports": ["error", {
        patterns: [{ group: ["**/adapters/**", "pg", "node:http"],
                     message: "app may use domain only; talk to the outside through ports." }],
      }],
    },
  },
];

$ npx eslint src
src/app/checkout.js
  1:1  error  '../adapters/postgres.js' import is restricted from being used by a pattern. app may use domain only; talk to the outside through ports  no-restricted-imports

✖ 1 problem (1 error, 0 warnings)

A deny-list has a weakness: it only forbids what you thought of. dependency-cruiser (v18 here) lets you write the rule as an allow-list — "domain may import only domain" — which also catches packages nobody listed:

module.exports = {
  forbidden: [
    { name: "domain-imports-only-domain", severity: "error",
      from: { path: "^src/domain" }, to: { pathNot: "^src/domain" } },
    { name: "app-imports-only-app-and-domain", severity: "error",
      from: { path: "^src/app" }, to: { pathNot: "^src/(app|domain)" } },
  ],
  options: { doNotFollow: { path: "node_modules" } }, // check our code, not our dependencies
};

$ npx depcruise src --config .dependency-cruiser.cjs

  error domain-imports-only-domain: src/domain/order.js → http

x 1 dependency violations (1 errors, 0 warnings). 9 modules, 12 dependencies cruised.

Evolving a legacy codebase

You'll rarely start fresh. More often there's a §02-style handler in production, earning money, and a rewrite would freeze features for months — then ship new bugs. The safe path is a series of small refactors, each one deployable:

Three techniques carry this:

• Characterization testsCharacterization testA test that records what existing code does today (right or wrong), so you notice if a refactor changes its behavior. Written before touching legacy code. first. They capture what the code does today — even the quirks — so you know when a refactor changed behavior.
• Extract the pure parts before adding interfaces. Pricing math needs no port; moving it into a function is a safe, quick first win.
• Branch by abstractionBranch by abstractionChanging a big piece of code in small safe steps: put an interface in front of the old code, move callers to the interface, build the new implementation behind it, then switch and delete the old one. for the rest: put a port in front of the old code, move callers onto the port, then replace what's behind it. At every step, the old path still works.

Move code when you touch it. Don't schedule a "migrate everything" project. Each new feature starts in the new structure; old code moves when a change takes you there anyway. That way the code that changes most often migrates first — which is exactly the code that benefits — and code nobody touches may never need to move at all.

How this relates to modular monoliths and DDD

Ports and adapters is about the structure inside one part of a system. Two neighbouring ideas work at a larger scale:

• A Modular monolithModular monolithA monolith whose code is split into modules with strict boundaries (each owns its data and exposes a small API to the others), so it keeps the simplicity of one deploy but can be split later if needed. splits one deployable app into modules with strict boundaries — checkout, catalog, payments — each owning its data and exposing a small API. Package-by-feature from §10, with architecture tests between features, is a modular monolith. Each module can use ports and adapters inside, or not. And if one module is later split into its own service, its ports make that much easier: the HTTP or queue adapter changes, the core doesn't. The trade-offs of that split are in Monolith vs Microservices.
• Domain-driven design answers the question this page skipped: what goes in the core, and where one module ends and the next begins. Its building blocks — entitiesEntityAn object defined by its identity, not its current values. Customer c-7 stays the same customer after changing name and address, and two customers named “Ana Lee” are still two different customers., value objectsValue objectA small type that wraps a value with its rules, e.g. Money that always carries its currency and can only be created through a constructor that checks it. Two value objects with the same contents count as equal., aggregatesAggregateA cluster of objects (an Order and its lines) that must stay consistent together, treated as one unit: changed only through its root, loaded and saved whole, in one transaction. — are how you design domain, and its bounded contextsBounded contextA part of the system inside which every word has exactly one meaning and one model. “Product” inside Catalog means a description with photos; inside Shipping it means a box with a weight. Each context has its own code and data. are how you draw the module lines. See Domain-Driven Design.

A short way to hold all three: DDD decides what the core is; ports and adapters keeps it clean; the modular monolith keeps the cores apart.

Pitfalls gallery

Check yourself

Decide on your answer before you click. Each explanation points back to the section that covers it.

// package app
import "shop/adapters/postgres" // to call postgres.Store directly

// package postgres (already there)
import "shop/app"               // to implement app.Tx

Cheat sheet