MiniCart: Hexagonal Architecture in Go

huzaifa nur — Sat, 11 Jul 2026 08:20:23 +0000

A hands-on Go architecture course that teaches hexagonal architecture, also
known as ports and adapters, by building a small e-commerce backend from
scratch.

The service you build is called MiniMart: a product catalog, an order system,
real PostgreSQL storage, Kafka-style events, Docker packaging, and tests. The
course starts with simple standard-library Go and grows the application one
deliberate boundary at a time.

If you are learning Golang clean architecture, DDD-lite, modular
monoliths, domain-driven design in Go, or production backend patterns, this
repo is meant to be read and typed through stage by stage.

What you'll build

MiniMart is an HTTP API with two domains - a product catalog and an order
system - and six endpoints:

Method	Path	Purpose
GET	`/health`	Liveness check
POST	`/v1/products`	Add a product
GET	`/v1/products`	List products
GET	`/v1/products/{id}`	Fetch a product
POST	`/v1/orders`	Place an order
GET	`/v1/orders/{id}`	Fetch an order

You build it with the standard library first (stages 01-10), then give it real
Postgres, Kafka, and Docker (stages 11-14).

Those tools are not the architecture. Go, Postgres, Kafka, Docker, or even
microservices can still produce a system that is painful to change. The point of
MiniMart is the habit underneath them: keep business decisions in one place, keep
technology at the edges, and make every boundary explicit enough that a future
change has somewhere obvious to land.

The rule

Every decision in this course follows from one rule:

Source-code dependencies point inward.
presentation → application → domain. Infrastructure implements interfaces the
domain defines; the domain never imports infrastructure.

The four layers, and who is allowed to import whom:

presentation/     input adapters   - HTTP handlers, Kafka consumers
      │ imports
      ▼
application/      use cases        - orchestration
      │ imports
      ▼
domain/           entities + ports - the core; defines the interfaces
      ▲
      │ implements the ports
infrastructure/   output adapters  - Postgres, Kafka producer

The domain sits in the centre and depends on nothing outward. That is what lets
you test business rules without a database, and swap Postgres for anything else
without touching business code. You'll prove both claims later.

Toolbox & working copy

Four tools carry the course:

Go 1.22+ - the language. 1.22 is the floor because routes use method-aware patterns like GET /v1/products/{id}.
Docker + Compose - runs Postgres and the Kafka broker locally from stage 11.
sqlc - turns plain SQL into type-safe Go (stage 11).
dbmate - runs versioned SQL migrations (stage 11).

You install sqlc and dbmate now so later stages don't stall on setup.

Check Go and Docker:

go version      # go1.22 or newer
docker version  # client + server both respond

Install the two extra CLIs (they land in $(go env GOPATH)/bin - make sure that's on your PATH):

go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
go install github.com/amacneil/dbmate/v2@latest
sqlc version
dbmate --version

Create your working copy. Make a fresh module in a directory you'll work in:

mkdir -p ~/minimart
cd ~/minimart
go mod init minimart
go build ./...

go build ./... should print nothing and exit 0. The module is just a go.mod so
far; you write everything else.

For this course: @latest keeps setup short. A team project should pin exact
tool versions in its Makefile and CI so every developer generates identical code.

Verify

go version && docker version && sqlc version && dbmate --version && \
  (cd ~/minimart && go build ./... && echo "module builds")

All four version lines print, and you see module builds.

Why hexagonal

Consider a handler written the "just make it work" way - one function doing
everything:

func handleCreateProduct(w http.ResponseWriter, r *http.Request) {
    var body map[string]any
    json.NewDecoder(r.Body).Decode(&body)               // HTTP concern
    if body["price"].(float64) <= 0 {                    // business rule
        w.WriteHeader(400)
        return
    }
    db.Exec("INSERT INTO products VALUES ($1, $2)", ...) // database concern
    w.WriteHeader(201)                                   // HTTP concern
}

You will never write this. Notice only that three unrelated jobs - parsing HTTP,
a business rule, and SQL - share one function body. That causes concrete problems:

You can't test the price rule without starting an HTTP server and a database.
You can't change the database without editing code that also does HTTP.
You can't reuse the price rule elsewhere without copying it.

The business rule - the one line that makes this your application - is trapped
between JSON parsing and a SQL string. It has no place of its own.

Hexagonal architecture (Alistair Cockburn's term; also "ports & adapters") gives
it one:

Put the business logic in the centre. Make everything that touches the outside
world - HTTP, databases, queues - a replaceable adapter around it.

The centre never imports the adapters. The adapters depend on the centre. The next
section states that as a rule and draws the map.

The Dependency Rule

The code is organised in four layers. Each may import only layers closer to the
centre:

presentation/     input adapters   - HTTP handlers, later Kafka consumers
      │ imports
      ▼
application/      use cases        - orchestrates the work
      │ imports
      ▼
domain/           entities + ports - business rules; defines the interfaces
      ▲
      │ implements the ports
infrastructure/   output adapters  - storage, message producers

The Dependency Rule:

Source-code dependencies point inward. presentation → application → domain.
Infrastructure implements interfaces the domain defines; the domain imports
nothing outward.

Read the arrows as "is allowed to import." Three point down toward the domain.
The fourth, from infrastructure/, points up - because infrastructure
implements a port (an interface) the domain owns, so it depends on the domain,
not the reverse.

Two consequences you'll rely on for the rest of the course:

The domain has no imports from HTTP or a database, so you can test it with no server and no DB.
Swapping one output adapter for another (in-memory → Postgres) touches no business code, because the business code depends on the port, not the adapter.

You don't need to memorise this. You'll build each layer in order, from the domain
outward, over stages 02-05.

Where `main.go` fits

None of the four layers. main.go is the composition root - the edge of the
program where all the layers get assembled and switched on. It is allowed to
import everything, because something has to plug the pieces together. You build a
minimal one next.

The health server

In a second terminal:

curl http://localhost:8080/health
# {"status":"ok"}

curl -i http://localhost:8080/nope | head -1
# HTTP/1.1 404 Not Found

The prompt may sit right after } - the response has no trailing newline, which
is fine.

In your minimart module, create main.go:

package main

import (
    "log"
    "net/http"
)

func main() {
    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        _, _ = w.Write([]byte(`{"status":"ok"}`))
    })

    log.Println("minimart listening on http://localhost:8080")
    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

Go note: since Go 1.22 the standard router reads the HTTP method as part of
the pattern ("GET /health"), so no framework is needed to route by method.

Run it:

go run .

main.go stays this small for a while. It's the composition root; the health
endpoint lives here - not in a domain - because "is this process up?" is an
operational question, not a business capability. It grows into a module-loading
boot sequence in stage 07.

What you learned

The Dependency Rule: imports point inward, toward the domain.
main.go is the composition root - it wires things together and owns operational endpoints like /health.
Go's net/http routes by method and path with no framework.

You won't touch this server again until stage 05. The next three stages build the
domain, application, and storage - all runnable with no network at all.

The Domain

Entities

An entity is a thing your business talks about, modelled as a plain Go type. The
catalog has one: a Product. Entities live in the domain layer - the centre of
the hexagon - and the domain imports nothing outward: no net/http, no database
driver, no JSON tags. Standard-library basics (strings, errors) are fine.

That ignorance is the point. Because Product knows nothing about how it is stored
or who is asking, you can test its rules with no server and no database, and swap in
Postgres later without touching it.

Here is the type (you write the file in the Valid by construction section, once its constructor exists):

// Product is a catalog entry. Prices are integer cents - never floats - so money
// arithmetic is exact. Code outside tests should create Product values through
// NewProduct, so normal application flow is valid by construction.
type Product struct {
    ID         string
    Name       string
    PriceCents int64
    Stock      int
}

Four exported fields, no methods, no tags. PriceCents is int64 (money is cents -
the Money in cents section explains why); Stock is a plain int, because a count is not a ledger entry.

Valid by construction

Scattering if price <= 0 checks across the codebase means every caller must
remember them, and the one that forgets creates an invalid Product. Give the type
one blessed door instead: a constructor that validates, so a Product created
through NewProduct is valid. If NewProduct returns a nil error, the product it
hands back needs no further checking - anywhere, ever.

Each failure is a named sentinel error: a package-level error value that
callers identify with errors.Is. The domain returns the sentinel; the HTTP edge
maps it to a status code later (stage 06). The domain itself knows nothing about HTTP.

Create catalog/domain/errors.go:

package domain

import "errors"

// Domain errors are exported sentinels. Callers compare with errors.Is; the HTTP
// edge maps them to status codes. The domain itself knows nothing about HTTP.
var (
    ErrProductNotFound  = errors.New("product not found")
    ErrEmptyName        = errors.New("product name must not be empty")
    ErrNonPositivePrice = errors.New("product price must be greater than zero")
    ErrNegativeStock    = errors.New("product stock must not be negative")
)

ErrProductNotFound has no caller yet - the repository port raises it in stage 03.

Create catalog/domain/product.go - the struct from the **Entities section plus its constructor:**

package domain

import "strings"

// Product is a catalog entry. Prices are integer cents - never floats - so money
// arithmetic is exact. Code outside tests should create Product values through
// NewProduct, so normal application flow is valid by construction.
type Product struct {
    ID         string
    Name       string
    PriceCents int64
    Stock      int
}

// NewProduct validates its inputs and returns a Product, or a domain error.
func NewProduct(id, name string, priceCents int64, stock int) (Product, error) {
    name = strings.TrimSpace(name)
    if name == "" {
        return Product{}, ErrEmptyName
    }
    if priceCents <= 0 {
        return Product{}, ErrNonPositivePrice
    }
    if stock < 0 {
        return Product{}, ErrNegativeStock
    }
    return Product{ID: id, Name: name, PriceCents: priceCents, Stock: stock}, nil
}

The constructor trims the name, rejects the three bad states, and otherwise returns
a valid value. id is not validated: it is never user input - the application layer
mints it (stage 04), so the domain takes it on trust. On failure it returns the zero
Product{}; the error tells the caller not to touch it.

Verify

go build ./catalog/domain/

Prints nothing, exits 0.

Money in cents

PriceCents is an int64 holding a whole number of cents - 1299 is $12.99. Money
is never a float64 in this codebase. The reason is exactness:

0.1 + 0.2 == 0.30000000000000004 // float64

Binary floating point cannot represent most decimal fractions exactly, so sums drift
by fractions of a cent. Across many rows that drift becomes real money the books
can't explain. Integers have no such error: cents add, compare, and total exactly.

int64 (not int) fixes the width at 64 bits on every platform - headroom for any
total, and a stable type across the wire and the database column. Convert to a
decimal string only at the outer edge, for display.

Table-driven tests

A table-driven test lists cases as a slice of structs and runs one loop over
them. Adding a case tomorrow costs one line, not a new function. Because the domain
imports nothing outward, this test needs no server and no database - it runs in
milliseconds.

Create catalog/domain/product_test.go:

package domain

import (
    "errors"
    "testing"
)

func TestNewProduct(t *testing.T) {
    tests := []struct {
        name        string
        productName string
        priceCents  int64
        stock       int
        wantErr     error
    }{
        {"valid", "Widget", 500, 3, nil},
        {"trims surrounding space", "  Widget  ", 500, 0, nil},
        {"empty name", "   ", 500, 0, ErrEmptyName},
        {"zero price", "Widget", 0, 0, ErrNonPositivePrice},
        {"negative price", "Widget", -1, 0, ErrNonPositivePrice},
        {"negative stock", "Widget", 500, -1, ErrNegativeStock},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            p, err := NewProduct("id-1", tt.productName, tt.priceCents, tt.stock)
            if tt.wantErr != nil {
                if !errors.Is(err, tt.wantErr) {
                    t.Fatalf("want error %v, got %v", tt.wantErr, err)
                }
                return
            }
            if err != nil {
                t.Fatalf("unexpected error: %v", err)
            }
            if p.Name != "Widget" {
                t.Fatalf("want trimmed name Widget, got %q", p.Name)
            }
        })
    }
}

Go note: a file ending _test.go compiles only under go test. Each
TestXxx(t *testing.T) runs automatically; t.Run(name, fn) makes each row a
named subtest. errors.Is reports whether an error matches a sentinel through any
%w wrapping.

The "trims surrounding space" row proves the constructor trims before validating:
" Widget " becomes "Widget", which is why the happy-path rows assert
p.Name == "Widget".

Verify

go test ./catalog/domain/

ok      minimart/catalog/domain 0.001s

Add -v to see each row by name.

Ports & Adapters

The port

The application will need to save and load products, but the domain must not know
how - that would drag a database into the centre. So the domain declares an
interface for what it needs and lets someone else implement it.

A port is an interface the domain owns, describing a capability it needs from the outside.
An adapter is a concrete type that satisfies a port (in-memory now, Postgres in stage 11).

Because the interface lives in domain/, the dependency arrow points inward: the
adapter imports the domain to implement the port; the domain imports nothing. That
is the Dependency Rule made concrete.

Every method takes ctx context.Context as its first parameter, from the very first
version. The in-memory store ignores it, but a real database adapter needs it for
cancellation, deadlines, tracing, and driver calls. Shaping the port for the real
adapter now avoids signature churn later. Do not hide required business inputs in
ctx, though - if a user ID, role, or tenant is needed to make a decision, pass it as
a typed argument where the compiler can see it.

A useful smell test for a port: could memory, Postgres, and maybe a remote API all
implement this interface without changing its vocabulary? If a domain port mentions
pgx, SQL, transactions, table names, or HTTP status codes, infrastructure leaked in.

Create catalog/domain/repository.go:

package domain

import "context"

// Repository is the persistence port the catalog domain needs. The domain owns
// this interface; adapters under infrastructure/ implement it (in-memory now,
// Postgres later). ctx is the first parameter of every method from the start -
// the shape a real database adapter requires.
type Repository interface {
    Save(ctx context.Context, p Product) error
    GetByID(ctx context.Context, id string) (Product, error)
    List(ctx context.Context) ([]Product, error)
}

GetByID returns ErrProductNotFound (the sentinel from the Valid by construction section) when the id is
unknown - the adapter's job in the in-memory adapter section.

Production note: a larger service can use sqlc-generated reader/ and writer/
query packages per domain. A hand-written repository can implement this port over
two pgxpool pools, sending reads to one and writes to the other while translating
pgx.ErrNoRows to ErrProductNotFound. The port remains unchanged.

Verify

go build ./catalog/domain/

Prints nothing, exits 0. An interface with no implementation still compiles.

The in-memory adapter

go build ./catalog/...

Prints nothing, exits 0. Rename Save to Store and the build fails at the var _
line - revert it.

An adapter lives in infrastructure/ and implements a domain port. The simplest
one keeps products in a map. It has no dependencies, starts instantly, and stays
useful as a fast test double even after Postgres becomes the runtime path.

One line earns its keep:

var _ domain.Repository = (*Repository)(nil)

This is a compile-time assertion. It assigns a nil *Repository to a throwaway
domain.Repository variable, forcing the compiler to check that *Repository
satisfies the interface. If a method signature drifts, the build fails here, at the
adapter, with a clear message - not at runtime, and not at some distant call site.

Create catalog/infrastructure/memory/repository.go:

// Package memory is an in-memory adapter for the catalog Repository port. Data
// lives only for the life of the process. It is the simplest possible adapter and
// stays useful forever as a fast, dependency-free double in tests.
package memory

import (
    "context"
    "sync"

    "minimart/catalog/domain"
)

// Repository stores products in a map guarded by a mutex, safe for concurrent use.
type Repository struct {
    mu       sync.RWMutex
    products map[string]domain.Product
}

// Compile-time proof that Repository satisfies the port. If a method drifts, the
// build fails here, not at runtime.
var _ domain.Repository = (*Repository)(nil)

func New() *Repository {
    return &Repository{products: make(map[string]domain.Product)}
}

func (r *Repository) Save(ctx context.Context, p domain.Product) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    r.products[p.ID] = p
    return nil
}

func (r *Repository) GetByID(ctx context.Context, id string) (domain.Product, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    p, ok := r.products[id]
    if !ok {
        return domain.Product{}, domain.ErrProductNotFound
    }
    return p, nil
}

func (r *Repository) List(ctx context.Context) ([]domain.Product, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    out := make([]domain.Product, 0, len(r.products))
    for _, p := range r.products {
        out = append(out, p)
    }
    return out, nil
}

The sync.RWMutex makes concurrent HTTP requests safe. GetByID returns
domain.ErrProductNotFound for an unknown id - the port's contract from the port section. The
ctx parameters go unused here; a database adapter would honour them.

The map stores domain.Product values, not pointers. That means a caller receives a
copy and cannot mutate the repository's internal state behind its back. For simple
entities, value copies are a cheap way to keep the adapter honest.

Test the adapter

The compile-time assertion proves the adapter fits the port; it does not prove the
adapter behaves. A short test does that: save a product, read it back, list it, and
confirm a missing id returns domain.ErrProductNotFound. Match the sentinel with
errors.Is, never by comparing message strings - the mapping at the HTTP edge
(stage 06) will depend on it.

Create catalog/infrastructure/memory/repository_test.go:

package memory

import (
    "context"
    "errors"
    "testing"

    "minimart/catalog/domain"
)

func TestRepository(t *testing.T) {
    ctx := context.Background()
    repo := New()

    p, err := domain.NewProduct("p-1", "Widget", 500, 3)
    if err != nil {
        t.Fatalf("NewProduct: %v", err)
    }

    // Save, then read the same product back.
    if err := repo.Save(ctx, p); err != nil {
        t.Fatalf("Save: %v", err)
    }
    got, err := repo.GetByID(ctx, "p-1")
    if err != nil {
        t.Fatalf("GetByID: %v", err)
    }
    if got != p {
        t.Fatalf("GetByID returned %+v, want %+v", got, p)
    }

    // List returns the one saved product.
    all, err := repo.List(ctx)
    if err != nil {
        t.Fatalf("List: %v", err)
    }
    if len(all) != 1 {
        t.Fatalf("List returned %d products, want 1", len(all))
    }

    // A missing id returns the domain not-found sentinel.
    if _, err := repo.GetByID(ctx, "missing"); !errors.Is(err, domain.ErrProductNotFound) {
        t.Fatalf("GetByID(missing): want ErrProductNotFound, got %v", err)
    }
}

context.Background() is the root context for tests and main - an empty,
never-cancelled context. got != p works because Product is a comparable struct
(every field is comparable).

Verify

go test ./catalog/infrastructure/memory/

ok      minimart/catalog/infrastructure/memory  0.002s

What you learned

A port is a domain-owned interface; an adapter in infrastructure/ implements it.
ctx leads every port method from the start, shaped for the real database.
The var _ Port = (*Adapter)(nil) assertion catches drift at compile time.

Next: the application layer orchestrates use cases over this port.

Use Cases

The service

The application layer holds use cases - the orchestration that turns a request
into domain calls and persistence. It sits between the outside adapters and the
domain, and depends only on interfaces: the domain entities and the Repository
port. It never names a concrete database or an HTTP type.

The Service holds the port as a field. The constructor takes it as a parameter -
dependency injection. Because the field is the interface, not a concrete type,
the caller decides what goes in: a test injects the in-memory adapter, production
injects Postgres, and the service code is identical either way. The place that makes
that choice is the composition root (stage 05's main.go, stage 07's module).

Create catalog/application/service.go:

package application

import "minimart/catalog/domain"

// Service is the catalog application layer. It orchestrates use cases over the
// domain and its ports, and depends only on interfaces - never on a concrete
// database or HTTP type.
type Service struct {
    repo domain.Repository
}

// NewService injects the repository port. The concrete adapter is chosen by the
// composition root, not here.
func NewService(repo domain.Repository) *Service {
    return &Service{repo: repo}
}

repo is unexported: nothing outside the package reaches the port directly; callers
go through the use-case methods you add next.

Verify

go build ./catalog/...

Prints nothing, exits 0. A service with a field and a constructor but no methods yet
still compiles.

One use case per file

Each use case is one method on Service, in its own file named after it
(create_product.go). The file tells you what the application does at a glance, and
a use case never grows tangled with unrelated ones.

CreateProduct takes a CreateProductRequest - an application DTO, distinct
from the HTTP request body you build in stage 05. Keeping them separate means the
wire format can change without touching the use case, and the use case can be called
from a Kafka consumer or a test with no HTTP in sight.

The ID is minted here, not accepted from the client. Recall the Valid by construction section: the domain takes
id on trust because the application controls it. IDs use crypto/rand, not
math/rand, so they are unguessable.

This use case is a command: it changes state. Later reads (GetProduct,
ListProducts) are queries: they ask questions and should not mutate anything.
That small split is CQRS-lite - useful vocabulary without new packages or ceremony.

Create catalog/application/create_product.go:

package application

import (
    "context"

    "minimart/catalog/domain"
)

// CreateProductRequest is the input to the CreateProduct use case. It is an
// application-layer type, distinct from any HTTP DTO.
type CreateProductRequest struct {
    Name       string
    PriceCents int64
    Stock      int
}

// CreateProduct mints an ID, builds a valid Product, and saves it through the port.
func (s *Service) CreateProduct(ctx context.Context, req CreateProductRequest) (domain.Product, error) {
    p, err := domain.NewProduct(newID(), req.Name, req.PriceCents, req.Stock)
    if err != nil {
        return domain.Product{}, err
    }
    if err := s.repo.Save(ctx, p); err != nil {
        return domain.Product{}, err
    }
    return p, nil
}

The use case validates by delegating to NewProduct - a bad request returns the
domain error unchanged, and nothing is saved. Only a valid product reaches the port.

Create catalog/application/id.go:

package application

import (
    "crypto/rand"
    "encoding/hex"
)

// newID returns a random 16-byte hex identifier.
func newID() string {
    b := make([]byte, 16)
    if _, err := rand.Read(b); err != nil {
        // crypto/rand failing means the OS entropy source is broken; there is no
        // sensible way to continue.
        panic(err)
    }
    return hex.EncodeToString(b)
}

The panic is deliberate: a failing entropy source is a broken program, not bad
input. Reserve panic for that; return errors for everything a caller might handle.

Verify

go build ./catalog/...

Prints nothing, exits 0.

Reads

Reads follow the same rule: one use case, one file. Right now each is a thin
pass-through to the port - no orchestration to do yet. That is fine. The seam still
earns its place: when a read later needs a rule (filter out-of-stock items, check
who is asking), the change lands in exactly one file, and the handler above it does
not move. The signature belongs to the use case even when the body is one line.

Reads are allowed to evolve differently from writes. If a screen later needs a
summary, search result, or denormalized shape, add a query/read model for that use
case instead of forcing domain.Product to become every view at once. MiniMart stays
simple today; the boundary keeps the option open.

Create catalog/application/get_product.go:

package application

import (
    "context"

    "minimart/catalog/domain"
)

// GetProduct returns a product by ID, or domain.ErrProductNotFound.
func (s *Service) GetProduct(ctx context.Context, id string) (domain.Product, error) {
    return s.repo.GetByID(ctx, id)
}

Create catalog/application/list_products.go:

package application

import (
    "context"

    "minimart/catalog/domain"
)

// ListProducts returns the whole catalog.
func (s *Service) ListProducts(ctx context.Context) ([]domain.Product, error) {
    return s.repo.List(ctx)
}

GetProduct passes domain.ErrProductNotFound straight up from the adapter; the
HTTP edge turns it into a 404 in stage 06.

Verify

go build ./catalog/...

Prints nothing, exits 0. The service now has all three catalog use cases: create,
get, and list. Save is the repository port's job, not a use case.

Test the use case

The test is itself a small composition root: it constructs the service with a
real adapter - NewService(memory.New()) - and drives the whole use case: mint an
ID, validate, save. No database, no HTTP server. That is the payoff of injecting the
port through the constructor: the same wiring that main does, a test can do in one
line.

The table checks the happy path (an ID is generated, the name survives) and each
validation error, which the use case passes through from NewProduct unchanged.

Create catalog/application/create_product_test.go:

package application

import (
    "context"
    "errors"
    "testing"

    "minimart/catalog/domain"
    "minimart/catalog/infrastructure/memory"
)

// The test is itself a small composition root: it injects the in-memory adapter,
// no database required.
func TestCreateProduct(t *testing.T) {
    tests := []struct {
        name    string
        req     CreateProductRequest
        wantErr error
    }{
        {"valid", CreateProductRequest{Name: "Widget", PriceCents: 500, Stock: 3}, nil},
        {"empty name", CreateProductRequest{Name: "  ", PriceCents: 500}, domain.ErrEmptyName},
        {"zero price", CreateProductRequest{Name: "Widget", PriceCents: 0}, domain.ErrNonPositivePrice},
        {"negative stock", CreateProductRequest{Name: "Widget", PriceCents: 500, Stock: -1}, domain.ErrNegativeStock},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            svc := NewService(memory.New())
            got, err := svc.CreateProduct(context.Background(), tt.req)
            if tt.wantErr != nil {
                if !errors.Is(err, tt.wantErr) {
                    t.Fatalf("want error %v, got %v", tt.wantErr, err)
                }
                return
            }
            if err != nil {
                t.Fatalf("unexpected error: %v", err)
            }
            if got.ID == "" {
                t.Fatal("expected a generated ID")
            }
            if got.Name != "Widget" {
                t.Fatalf("want name Widget, got %q", got.Name)
            }
        })
    }
}

The application test may import infrastructure/memory - a test file is not the
application layer, and the in-memory adapter is a legitimate test double. The
production code under test still imports only the port.

Verify

go test ./catalog/application/

ok      minimart/catalog/application    0.003s

What you learned

The application layer orchestrates use cases and depends only on the port.
One use case per file; the application DTO is separate from the wire DTO.
Injecting the port makes a test a composition root - no external infrastructure needed.

Next: the HTTP input adapter, the program's front door.

The Front Door

Input adapters & DTOs

The presentation layer holds input adapters - HTTP handlers now, Kafka consumers
later. An input adapter translates between an outside protocol (JSON on the wire) and
the application layer. It carries no business rules.

Its wire types are DTOs (data transfer objects), and they are deliberately not
the domain entity:

createProductRequest - the JSON body the API accepts.
productResponse - the JSON the API returns.

Keeping these separate from domain.Product means the public wire contract stays
stable even if the entity changes shape, and the entity stays free of json tags
(recall the Entities section). The json:"price_cents" tags live here, at the edge, where wire format
belongs.

This is intentional duplication, not waste. DRY is about one decision having one
home; it does not mean every similar struct must collapse into one type. The entity,
the HTTP response, and later the cross-domain contract have different audiences and
different reasons to change.

Create catalog/presentation/http/dto.go:

// Package http is the catalog's input adapter for HTTP. It translates between the
// wire (JSON) and the application layer, and never contains business rules.
package http

import "minimart/catalog/domain"

// createProductRequest is the JSON body accepted by POST /v1/products.
type createProductRequest struct {
    Name       string `json:"name"`
    PriceCents int64  `json:"price_cents"`
    Stock      int    `json:"stock"`
}

// productResponse is the JSON returned to clients. It is kept separate from the
// domain entity so the wire contract stays stable even if the entity changes.
type productResponse struct {
    ID         string `json:"id"`
    Name       string `json:"name"`
    PriceCents int64  `json:"price_cents"`
    Stock      int    `json:"stock"`
}

func toProductResponse(p domain.Product) productResponse {
    return productResponse{
        ID:         p.ID,
        Name:       p.Name,
        PriceCents: p.PriceCents,
        Stock:      p.Stock,
    }
}

toProductResponse is the one-way map from entity to wire type. There is no reverse
map: the handler reads the request DTO's fields into the application DTO by hand
(the Handlers section), so the two shapes can diverge without a struct-copy trick hiding it.

Verify

go build ./catalog/...

Prints nothing, exits 0. The request and response types are unused so far - Go
allows unused package-level types; it rejects only unused imports and locals.

Handlers

A handler is a method on Handlers that does three things: decode the request DTO,
call one use case, encode the response DTO. No business logic - that lives in the
domain and application layers below it. Two small helpers, writeJSON and
errorResponse, keep response writing in one place.

Error handling here is a stopgap. Each handler writes a single hard-coded status
on failure. That is honest enough to run, but wrong in detail: a not-found and a
validation failure should not share a status. Stage 06 replaces every stopgap branch
with respondDomainError, one function that maps each domain error to the right code.

Create catalog/presentation/http/response.go with the two helpers:

package http

import (
    "encoding/json"
    "net/http"
)

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

type errorResponse struct {
    Error string `json:"error"`
}

This file grows in stage 06: respondDomainError joins these helpers, and the
handler stopgaps below are rewired to call it.

Create catalog/presentation/http/create_product.go:

package http

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

    "minimart/catalog/application"
)

// Handlers holds the catalog HTTP handlers and their one dependency: the service.
type Handlers struct {
    svc *application.Service
}

func NewHandlers(svc *application.Service) *Handlers {
    return &Handlers{svc: svc}
}

func (h *Handlers) CreateProduct(w http.ResponseWriter, r *http.Request) {
    var req createProductRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeJSON(w, http.StatusBadRequest, errorResponse{"invalid JSON body"})
        return
    }
    p, err := h.svc.CreateProduct(r.Context(), application.CreateProductRequest{
        Name:       req.Name,
        PriceCents: req.PriceCents,
        Stock:      req.Stock,
    })
    if err != nil {
        // Stage 05 stopgap: any service error becomes a 400. Stage 06 replaces this
        // with respondDomainError, which sorts 400 from 404 from 500.
        writeJSON(w, http.StatusBadRequest, errorResponse{err.Error()})
        return
    }
    writeJSON(w, http.StatusCreated, toProductResponse(p))
}

The handler copies the request DTO into the application DTO field by field, then
maps the returned entity out through toProductResponse. Domain types never reach
the wire directly.

The field-by-field copy is deliberately boring. A generic struct copier would save a
few keystrokes but hide the contract decision: which external fields are accepted,
which internal fields are ignored, and which names belong to the API instead of the
domain.

Create catalog/presentation/http/get_product.go:

package http

import "net/http"

func (h *Handlers) GetProduct(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    p, err := h.svc.GetProduct(r.Context(), id)
    if err != nil {
        // Stage 05 stopgap: treat any error as not-found. Stage 06 distinguishes a
        // real 404 from a 500 with respondDomainError.
        writeJSON(w, http.StatusNotFound, errorResponse{err.Error()})
        return
    }
    writeJSON(w, http.StatusOK, toProductResponse(p))
}

r.PathValue("id") reads the {id} segment from the route pattern (Go 1.22+).

Create catalog/presentation/http/list_products.go:

package http

import "net/http"

func (h *Handlers) ListProducts(w http.ResponseWriter, r *http.Request) {
    ps, err := h.svc.ListProducts(r.Context())
    if err != nil {
        // Stage 05 stopgap: report a generic 500. Stage 06 routes this through
        // respondDomainError.
        writeJSON(w, http.StatusInternalServerError, errorResponse{"internal error"})
        return
    }
    out := make([]productResponse, 0, len(ps))
    for _, p := range ps {
        out = append(out, toProductResponse(p))
    }
    writeJSON(w, http.StatusOK, out)
}

make([]productResponse, 0, len(ps)) starts a non-nil, empty slice, so an empty
catalog encodes as [], not null.

Verify

go build ./catalog/...

Prints nothing, exits 0. Nothing serves these handlers yet - that is the Wire it section.

Wire it

Run the server:

go run .
# minimart listening on http://localhost:8080

In a second terminal, create then read back a product:

curl -s -X POST localhost:8080/v1/products \
  -d '{"name":"Widget","price_cents":500,"stock":3}'
# {"id":"<hex>","name":"Widget","price_cents":500,"stock":3}

curl -s localhost:8080/v1/products
# [{"id":"<hex>","name":"Widget","price_cents":500,"stock":3}]

curl -s localhost:8080/v1/products/<hex>   # paste the id from above
# {"id":"<hex>","name":"Widget","price_cents":500,"stock":3}

The store is in memory, so the product is gone when you restart the server.

main.go is the composition root - the one place allowed to import every layer,
because something has to assemble them. It picks the concrete adapter, injects it up
through the constructors, and registers the routes:

memory.New() → application.NewService → NewHandlers → Register(mux)

That chain is the Dependency Rule paid off: swapping storage is one line here, and no
layer below knows or cares. /health stays in the root - it answers an operational
question, not a business one.

This main.go is deliberately hand-wired and small. Stage 07 rewrites it into the
module pattern, where each domain wires itself and main just boots the modules. For
now, explicit wiring makes the whole graph visible on one screen.

Create catalog/presentation/http/routes.go:

package http

import "net/http"

// Register wires the catalog routes onto the shared mux. Method-aware patterns
// (Go 1.22+) let the standard router dispatch without a framework.
func (h *Handlers) Register(mux *http.ServeMux) {
    mux.HandleFunc("POST /v1/products", h.CreateProduct)
    mux.HandleFunc("GET /v1/products", h.ListProducts)
    mux.HandleFunc("GET /v1/products/{id}", h.GetProduct)
}

Replace main.go with the wired version:

package main

import (
    "log"
    "net/http"

    "minimart/catalog/application"
    "minimart/catalog/infrastructure/memory"
    cataloghttp "minimart/catalog/presentation/http"
)

func main() {
    mux := http.NewServeMux()

    // /health lives in the composition root, not a domain: it answers "is this
    // process up?", an operational question, not a business capability.
    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        _, _ = w.Write([]byte(`{"status":"ok"}`))
    })

    // Composition root: choose the concrete adapter, inject it up the layers, and
    // register the routes. Stage 07 replaces this hand-wiring with the module pattern.
    repo := memory.New()
    svc := application.NewService(repo)
    handlers := cataloghttp.NewHandlers(svc)
    handlers.Register(mux)

    log.Println("minimart listening on http://localhost:8080")
    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

Go note: cataloghttp is an import alias - the package is named http, which
would collide with the standard net/http, so the local name disambiguates.

What you learned

The presentation layer is an input adapter: decode, call a use case, encode.
Wire DTOs stay separate from the entity to keep the contract stable.
main.go is the composition root; it injects the adapter and owns /health.

Next: the stopgap error branches become one honest translation layer.

Honest Errors

Translate at the edge

The stage-05 handlers each guessed a status code in their own error branch. That
works by luck and fails in three ways:

It leaks. The create handler wrote err.Error() straight into the response. Today that string is a safe domain message, but the day a Postgres adapter returns pq: duplicate key value violates unique constraint "products_pkey", the stopgap ships table names and driver internals to the client - information disclosure, and a message text clients start depending on.
It duplicates. The same "not-found is 404" decision is copied into every handler, so the handlers drift apart over time.
It pushes HTTP inward. If a deeper layer decided status codes, the domain would have to import net/http - breaking the Dependency Rule.

The fix is one rule: translate errors at the edge. Deeper layers return typed
domain sentinels (the Valid by construction section) and nothing else. A single function at the HTTP boundary owns
the mapping from sentinel to status and to the client-facing message. Anything it
does not recognise collapses to a generic 500 internal error - a fixed string - so
internal detail never crosses the boundary.

Two things stay true at once: clients get honest, stable status codes, and the core
stays HTTP-agnostic and testable.

Production note: the same discipline draws the line between a 4xx the caller can
fix and a 5xx that pages an on-call engineer. A correct mapping is what makes
dashboards and alerts mean anything.

Map domain errors

Run the server (go run .), then in a second terminal:

curl -s -o /dev/null -w "%{http_code}\n" localhost:8080/v1/products/nope
# 404

curl -s -w " %{http_code}\n" -X POST localhost:8080/v1/products \
  -d '{"name":"Bad","price_cents":0,"stock":1}'
# {"error":"product price must be greater than zero"} 400

A missing product is a 404 and an invalid price a 400 - decided in one function, not
three.

respondDomainError is the one function that turns a domain sentinel into an HTTP
status. It matches with errors.Is, so it still works when a lower layer wraps a
sentinel with %w. The order is deliberate: known errors map to 404 or 400; the
default catches everything else as a generic 500.

Extend catalog/presentation/http/response.go - add the errors and domain imports and the mapping function (the two helpers from the **Handlers section stay):**

package http

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

    "minimart/catalog/domain"
)

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

type errorResponse struct {
    Error string `json:"error"`
}

// respondDomainError is the single place that maps a domain error to an HTTP
// status. Translation happens only at the edge; deeper layers never import
// net/http. A message we don't recognise becomes a generic 500, so internal
// details never leak to clients.
func respondDomainError(w http.ResponseWriter, err error) {
    switch {
    case errors.Is(err, domain.ErrProductNotFound):
        writeJSON(w, http.StatusNotFound, errorResponse{err.Error()})
    case errors.Is(err, domain.ErrEmptyName),
        errors.Is(err, domain.ErrNonPositivePrice),
        errors.Is(err, domain.ErrNegativeStock):
        writeJSON(w, http.StatusBadRequest, errorResponse{err.Error()})
    default:
        writeJSON(w, http.StatusInternalServerError, errorResponse{"internal error"})
    }
}

Replace the stopgap error branch in each handler with a single call. In create_product.go:

    if err != nil {
        respondDomainError(w, err)
        return
    }

get_product.go and list_products.go change the same way - delete the guessed
status and call respondDomainError(w, err). All three now read identically at the
error branch, and the mapping lives in exactly one place. For reference,
get_product.go in full:

package http

import "net/http"

func (h *Handlers) GetProduct(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    p, err := h.svc.GetProduct(r.Context(), id)
    if err != nil {
        respondDomainError(w, err)
        return
    }
    writeJSON(w, http.StatusOK, toProductResponse(p))
}

What you learned

Error translation happens once, at the edge; deeper layers stay HTTP-free.
errors.Is matches sentinels through %w wrapping.
Unrecognised errors collapse to a generic 500, so internals never leak.

The catalog is now a complete vertical slice. Stage 07 makes it wire itself as a
module, so main.go stops hand-assembling the graph.

The Module Pattern

Why modules

By stage 06, main.go builds the catalog by hand:

repo := memory.New()
svc := application.NewService(repo)
handlers := cataloghttp.NewHandlers(svc)
handlers.Register(mux)

Four lines, one domain. Now project forward. MiniMart is about to grow an order
domain (stage 08), and a larger application keeps going - users, payments, inventory,
notifications. Each brings a repository, a service, HTTP routes, and later
background workers. With this style, every one of those lines lands in main.go,
and main.go imports every package of every domain: each memory, application,
and presentation/http.

Two costs compound:

main.go knows everyone's internals. It names each domain's concrete adapter and handler types. A change to how the catalog stores data is a change to main.go.
Nothing is sealed. Any domain's guts are one import away from any other. "Who may call what" becomes a convention people remember, not a boundary the code enforces.

The fix inverts the wiring. Instead of main.go reaching into each domain, each
domain exposes one small object that knows how to build and plug in itself.
main.go shrinks to a list of those objects and a loop.

That structure has a name: a modular monolith. One binary, one process - but
internally, sealed domains standing side by side, each wiring itself and (from
stage 09) reaching the others only through published contracts. You get much of the
discipline of microservices with none of the network.

This stage adds no endpoint. It restructures the wiring so stages 08-10 have
somewhere to stand.

Production note: this structure can support many domains in one binary while
keeping main.go to a list and a loop; each domain carries its own wiring.

The Module interface

A module is a domain's self-wiring unit. To let main.go treat every domain
identically, they all satisfy one interface. It lives in pkg/ - the home for code
shared by all domains and owned by none (plumbing only; no business logic).

The interface declares four methods, called in phases during boot:

Name() - identifies the module in boot logs and errors.
Init(ctx) - build the domain's internals (service, adapters).
RegisterContracts(ctx, c) - publish this domain's contract into a shared registry so other domains can call it. Empty until stage 09.
RegisterHTTP(ctx, mux) - wire this domain's routes onto the mux.

ctx is threaded through even though nothing uses it yet: when Init starts doing
work that can block - opening a Postgres pool in stage 11 - cancellation and
timeouts already have a lane.

Create pkg/module/contracts/contracts.go. It starts as an empty registry; stage 09 fills it with contract slots and a Verify() method:

package contracts

// Contracts is the shared registry modules publish their contracts into. It is
// empty now; stage 09 gives it one slot per published contract, plus Verify().
type Contracts struct{}

Create pkg/module/module.go:

package module

import (
    "context"
    "net/http"

    "minimart/pkg/module/contracts"
)

// Module is one self-contained domain in the modular monolith.
//
// The boot sequence in main.go calls these methods in phases, for every module:
//
//  1. Init             build the module's own internals (service, adapters).
//  2. RegisterContracts publish this module's contract into the shared registry.
//  3. (Verify)         main.go fails the boot if any contract slot is still nil.
//  4. RegisterHTTP     wire this module's routes onto the mux.
//
// No module may call another module before phase 3 completes.
type Module interface {
    Name() string
    Init(ctx context.Context) error
    RegisterContracts(ctx context.Context, c *contracts.Contracts) error
    RegisterHTTP(ctx context.Context, mux *http.ServeMux) error
}

Go note: an interface lists method signatures with no bodies. Any type with
all four methods satisfies Module automatically - no implements keyword, no
registration. That is what lets main.go hold a []module.Module without
importing a single concrete domain type.

The phase comment describes where this is going. This stage wires phases 1, 2, and
4; the Verify() gate (phase 3) arrives in stage 09, when there is a contract to
verify.

Grows later: stage 09 gives RegisterContracts a real body, and expands the
empty Contracts registry above. Stage 12 adds a fifth method,
RegisterWorkers(ctx, w), for Kafka consumers - the worker process registers
those and skips HTTP.

Verify

go build ./pkg/...

Prints nothing, exits 0. Nothing implements Module yet - that's the next section.

A self-wiring domain

The wiring main.go did by hand becomes the catalog's own Module. This file sits
in the domain's root folder (catalog/module.go, package catalog), above the
four layers - it is the catalog's composition root, the one place that names a
concrete adapter.

Create catalog/module.go:

// Package catalog wires the catalog domain into the modular monolith. It is the
// domain's composition root: the one place that names concrete adapters.
package catalog

import (
    "context"
    "net/http"

    "minimart/catalog/application"
    "minimart/catalog/infrastructure/memory"
    cataloghttp "minimart/catalog/presentation/http"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
)

// Module is the catalog domain's self-wiring unit.
type Module struct {
    svc      *application.Service
    handlers *cataloghttp.Handlers
}

var _ module.Module = (*Module)(nil)

func NewModule() *Module { return &Module{} }

func (m *Module) Name() string { return "catalog" }

// Init builds the domain's internals and chooses the concrete storage adapter.
// Swapping storage is a one-line change here; no other layer is touched.
func (m *Module) Init(ctx context.Context) error {
    repo := memory.New()
    m.svc = application.NewService(repo)
    m.handlers = cataloghttp.NewHandlers(m.svc)
    return nil
}

// RegisterContracts is a no-op for now. Stage 09 gives it a body that publishes the
// catalog contract into the shared registry so other domains can call it.
func (m *Module) RegisterContracts(ctx context.Context, c *contracts.Contracts) error {
    return nil
}

// RegisterHTTP wires the catalog routes onto the mux.
func (m *Module) RegisterHTTP(ctx context.Context, mux *http.ServeMux) error {
    m.handlers.Register(mux)
    return nil
}

The compile-time assertion var _ module.Module = (*Module)(nil) proves at build
time that *Module satisfies the interface. Two Module names share that line:
module.Module is the interface from pkg/module; the bare Module is the
catalog's struct.

Init is where the storage choice is named - memory.New(). That single line is
what stage 11 changes to swap in Postgres; no other layer is touched.

RegisterContracts is a no-op for now - the catalog has no published contract yet.
Stage 09 gives it a body.

Production note: NewModule can receive shared infrastructure - a Postgres pool,
a Kafka producer, and a logger - while Init passes those dependencies to
sqlc-backed repositories. The structure stays the same as the dependencies grow.

Verify

go build ./...

Builds. main.go still wires the catalog the old way - you rewrite it next, and
the server keeps serving products.

The boot loop

go run .

In a second terminal, your stage-06 curls still pass - same endpoints, same output:

curl -s -X POST http://localhost:8080/v1/products \
  -d '{"name":"Widget","price_cents":1299,"stock":10}'
# → the created product as JSON

curl -s -i http://localhost:8080/v1/products/ghost | head -1
# → HTTP/1.1 404 Not Found

With the catalog wiring itself, main.go no longer needs to know what a catalog is.
It holds a []module.Module and runs each lifecycle phase across the whole slice
before starting the next. Running phase by phase - all Inits, then all
RegisterContracts, then all RegisterHTTP - rather than fully booting one module
before the next, is what lets modules depend on each other from stage 09: by the
time routes go live, every module is built and every contract is published.

Rewrite main.go:

package main

import (
    "context"
    "log"
    "net/http"

    "minimart/catalog"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
)

func main() {
    ctx := context.Background()

    mux := http.NewServeMux()

    // /health lives in the composition root, not a domain: it answers "is this
    // process up?", an operational question, not a business capability.
    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        _, _ = w.Write([]byte(`{"status":"ok"}`))
    })

    // One registry pointer, shared by every module. It is empty now; stage 09
    // gives it slots and a Verify() gate.
    registry := &contracts.Contracts{}

    modules := []module.Module{
        catalog.NewModule(),
    }

    // Phase 1 - build each module's internals.
    for _, m := range modules {
        if err := m.Init(ctx); err != nil {
            log.Fatalf("init %s: %v", m.Name(), err)
        }
    }
    // Phase 2 - each module publishes its contract (a no-op until stage 09).
    for _, m := range modules {
        if err := m.RegisterContracts(ctx, registry); err != nil {
            log.Fatalf("register contracts %s: %v", m.Name(), err)
        }
    }
    // Phase 3 - wire HTTP routes.
    for _, m := range modules {
        if err := m.RegisterHTTP(ctx, mux); err != nil {
            log.Fatalf("register http %s: %v", m.Name(), err)
        }
    }

    log.Println("minimart listening on http://localhost:8080")
    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

main.go now imports minimart/catalog - the domain's front gate - and nothing
about memory, application, or handler packages. Adding a domain costs one line
in the modules slice; stage 08 proves it.

The registry is created and passed through, but it is empty and every
RegisterContracts is a no-op today. Stage 09 fills the registry and inserts a
Verify() gate between phases 2 and 3 - fail the boot loudly if a module forgot to
register, rather than nil-panic on the first request.

Production note: a production boot sequence also needs a closing act: trap SIGTERM, call
http.Server.Shutdown, let in-flight requests finish before exit. log.Fatal is
fine for MiniMart; the ceremony is symmetric.

What you learned

Each domain wires itself; main.go is a list and a loop.
Boot runs in phases across all modules, not one module at a time.
pkg/ holds shared, business-free plumbing.

A Second Domain

The order entity

An order line stores a ProductID, but also copies the product's Name and
UnitPriceCents into itself. That looks redundant - the price is in the catalog.
But the catalog's price will change, and a placed order must not change with it. An
order records what the deal was. So Item snapshots the name and price at
order time.

Like Product, Order is valid by construction: NewOrder is the only way to make
one. It validates the lines, computes each line total and the order total in integer
cents, and stamps CreatedAt.

Create order/domain/order.go:

package domain

import "time"

// Item is one line of an order. Name and UnitPriceCents are a snapshot captured
// when the order is placed, so later catalog price or name changes never rewrite
// past orders.
type Item struct {
    ProductID      string
    Name           string
    UnitPriceCents int64
    Quantity       int
    LineTotalCents int64
}

// Order is a placed order. Like Product, it is valid by construction: NewOrder is
// the only way to make one.
type Order struct {
    ID         string
    UserID     string
    Items      []Item
    TotalCents int64
    CreatedAt  time.Time
}

// NewOrder validates the lines, computes each LineTotalCents and the order
// TotalCents, and stamps CreatedAt. Callers pass items whose UnitPriceCents were
// already resolved from an authoritative source (the catalog) - never the client.
func NewOrder(id, userID string, items []Item) (Order, error) {
    if len(items) == 0 {
        return Order{}, ErrNoItems
    }
    var total int64
    for i := range items {
        if items[i].Quantity <= 0 {
            return Order{}, ErrInvalidQuantity
        }
        items[i].LineTotalCents = items[i].UnitPriceCents * int64(items[i].Quantity)
        total += items[i].LineTotalCents
    }
    return Order{
        ID:         id,
        UserID:     userID,
        Items:      items,
        TotalCents: total,
        CreatedAt:  time.Now().UTC(),
    }, nil
}

NewOrder's doc comment already describes where this domain is headed: prices
"resolved from an authoritative source (the catalog) - never the client." In this
stage the order service still feeds it prices from the request; stage 10 makes the
comment literally true. The domain code does not change - only the wiring around it.

Create order/domain/errors.go:

package domain

import "errors"

var (
    ErrOrderNotFound   = errors.New("order not found")
    ErrNoItems         = errors.New("order must contain at least one item")
    ErrInvalidQuantity = errors.New("item quantity must be greater than zero")
)

Go note: package domain again - the same short name as the catalog's. Package
names only need to be unique within an import path, and minimart/order/domain
differs from minimart/catalog/domain. Every domain repeats the same four-layer
naming; uniformity is the point.

Verify

go build ./order/...

Builds. No behavior yet - the port, adapter, and use cases come next.

Port and adapter

Same drill as the catalog: the domain owns a Repository interface (the port), and
infrastructure/memory implements it. Orders need only Save and GetByID - no
List, because no use case lists orders. A port declares exactly what the domain
needs, no more.

Create order/domain/repository.go:

package domain

import "context"

// Repository is the persistence port for orders.
type Repository interface {
    Save(ctx context.Context, o Order) error
    GetByID(ctx context.Context, id string) (Order, error)
}

Create order/infrastructure/memory/repository.go:

package memory

import (
    "context"
    "sync"

    "minimart/order/domain"
)

type Repository struct {
    mu     sync.RWMutex
    orders map[string]domain.Order
}

var _ domain.Repository = (*Repository)(nil)

func New() *Repository {
    return &Repository{orders: make(map[string]domain.Order)}
}

func (r *Repository) Save(ctx context.Context, o domain.Order) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    r.orders[o.ID] = o
    return nil
}

func (r *Repository) GetByID(ctx context.Context, id string) (domain.Order, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    o, ok := r.orders[id]
    if !ok {
        return domain.Order{}, domain.ErrOrderNotFound
    }
    return o, nil
}

The compile-time assertion var _ domain.Repository = (*Repository)(nil) fails the
build if a method drifts.

Production note: this slot can hold a Postgres adapter instead, backed by sqlc-generated
reader/ and writer/ packages under order/infrastructure/postgres/. The port
is unchanged; only the adapter behind it gets heavier. You do that swap for both
catalog and order in stage 11.

Verify

go build ./order/...

Builds.

Place order

PlaceOrder takes a request, builds domain.Items, calls NewOrder, and saves.
The question is where each item's price comes from.

The order domain cannot reach the catalog yet - cross-domain calls are stages 09-10.
So at this stage the request carries the price, and the service trusts it. State that
plainly: the order domain uses a price it did not compute. That is a coupling and
trust-boundary problem - the caller can send any number. Stage 10 removes it by
fetching each price from the catalog. The final PlaceOrder we are heading toward
resolves prices through the catalog contract; this intermediate one does not.

order/application/service.go:

package application

import "minimart/order/domain"

// Service is the order application layer. For now it depends only on the order
// repository port. In stage 10 it gains a second dependency - the catalog contract -
// so it can resolve real prices instead of trusting the caller.
type Service struct {
    repo domain.Repository
}

func NewService(repo domain.Repository) *Service {
    return &Service{repo: repo}
}

order/application/id.go:

package application

import (
    "crypto/rand"
    "encoding/hex"
)

func newID() string {
    b := make([]byte, 16)
    if _, err := rand.Read(b); err != nil {
        panic(err)
    }
    return hex.EncodeToString(b)
}

order/application/place_order.go:

package application

import (
    "context"

    "minimart/order/domain"
)

// PlaceOrderRequest is the input to PlaceOrder. At this stage each item carries a
// Name and UnitPriceCents sent by the caller. The order domain has no way to reach
// the catalog yet, so it trusts these values - a price it did not compute. Stage 10
// removes both fields and fetches the price from the catalog instead.
type PlaceOrderRequest struct {
    UserID string
    Items  []PlaceOrderItem
}

type PlaceOrderItem struct {
    ProductID      string
    Name           string
    UnitPriceCents int64
    Quantity       int
}

func (s *Service) PlaceOrder(ctx context.Context, req PlaceOrderRequest) (domain.Order, error) {
    if len(req.Items) == 0 {
        return domain.Order{}, domain.ErrNoItems
    }
    items := make([]domain.Item, 0, len(req.Items))
    for _, it := range req.Items {
        if it.Quantity <= 0 {
            return domain.Order{}, domain.ErrInvalidQuantity
        }
        items = append(items, domain.Item{
            ProductID:      it.ProductID,
            Name:           it.Name,
            UnitPriceCents: it.UnitPriceCents,
            Quantity:       it.Quantity,
        })
    }
    order, err := domain.NewOrder(newID(), req.UserID, items)
    if err != nil {
        return domain.Order{}, err
    }
    if err := s.repo.Save(ctx, order); err != nil {
        return domain.Order{}, err
    }
    return order, nil
}

order/application/get_order.go:

package application

import (
    "context"

    "minimart/order/domain"
)

func (s *Service) GetOrder(ctx context.Context, id string) (domain.Order, error) {
    return s.repo.GetByID(ctx, id)
}

Verify

go build ./order/...

Builds. PlaceOrderItem carries Name and UnitPriceCents from the caller - the
fields stage 10 removes once prices come from the catalog.

Order HTTP

Same edge pattern as the catalog: a Handlers struct holding the service, a
response.go with the JSON helpers and the error translator, DTOs with JSON tags,
and a Register that maps routes. The request DTO mirrors the current use case - it
still carries name and unit_price_cents. Stage 10 strips both.

order/presentation/http/dto.go:

package http

import (
    "time"

    "minimart/order/domain"
)

// placeOrderRequest is the body of POST /v1/orders. At this stage each item carries
// a name and unit price from the client. Stage 10 strips both fields: the client
// will name products and quantities only, and prices come from the catalog.
type placeOrderRequest struct {
    UserID string           `json:"user_id"`
    Items  []placeOrderItem `json:"items"`
}

type placeOrderItem struct {
    ProductID      string `json:"product_id"`
    Name           string `json:"name"`
    UnitPriceCents int64  `json:"unit_price_cents"`
    Quantity       int    `json:"quantity"`
}

type orderResponse struct {
    ID         string         `json:"id"`
    UserID     string         `json:"user_id"`
    Items      []itemResponse `json:"items"`
    TotalCents int64          `json:"total_cents"`
    CreatedAt  string         `json:"created_at"`
}

type itemResponse struct {
    ProductID      string `json:"product_id"`
    Name           string `json:"name"`
    UnitPriceCents int64  `json:"unit_price_cents"`
    Quantity       int    `json:"quantity"`
    LineTotalCents int64  `json:"line_total_cents"`
}

func toOrderResponse(o domain.Order) orderResponse {
    items := make([]itemResponse, 0, len(o.Items))
    for _, it := range o.Items {
        items = append(items, itemResponse{
            ProductID:      it.ProductID,
            Name:           it.Name,
            UnitPriceCents: it.UnitPriceCents,
            Quantity:       it.Quantity,
            LineTotalCents: it.LineTotalCents,
        })
    }
    return orderResponse{
        ID:         o.ID,
        UserID:     o.UserID,
        Items:      items,
        TotalCents: o.TotalCents,
        CreatedAt:  o.CreatedAt.Format(time.RFC3339),
    }
}

order/presentation/http/response.go:

package http

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

    "minimart/order/domain"
)

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

type errorResponse struct {
    Error string `json:"error"`
}

// respondDomainError maps order-domain errors to HTTP status codes. Stage 10 adds
// one more case - the catalog contract's ErrProductNotFound - once the order
// service starts resolving products through the catalog.
func respondDomainError(w http.ResponseWriter, err error) {
    switch {
    case errors.Is(err, domain.ErrOrderNotFound):
        writeJSON(w, http.StatusNotFound, errorResponse{err.Error()})
    case errors.Is(err, domain.ErrNoItems),
        errors.Is(err, domain.ErrInvalidQuantity):
        writeJSON(w, http.StatusBadRequest, errorResponse{err.Error()})
    default:
        writeJSON(w, http.StatusInternalServerError, errorResponse{"internal error"})
    }
}

order/presentation/http/place_order.go:

package http

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

    "minimart/order/application"
)

type Handlers struct {
    svc *application.Service
}

func NewHandlers(svc *application.Service) *Handlers {
    return &Handlers{svc: svc}
}

func (h *Handlers) PlaceOrder(w http.ResponseWriter, r *http.Request) {
    var req placeOrderRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeJSON(w, http.StatusBadRequest, errorResponse{"invalid JSON body"})
        return
    }
    items := make([]application.PlaceOrderItem, 0, len(req.Items))
    for _, it := range req.Items {
        items = append(items, application.PlaceOrderItem{
            ProductID:      it.ProductID,
            Name:           it.Name,
            UnitPriceCents: it.UnitPriceCents,
            Quantity:       it.Quantity,
        })
    }
    o, err := h.svc.PlaceOrder(r.Context(), application.PlaceOrderRequest{
        UserID: req.UserID,
        Items:  items,
    })
    if err != nil {
        respondDomainError(w, err)
        return
    }
    writeJSON(w, http.StatusCreated, toOrderResponse(o))
}

order/presentation/http/get_order.go:

package http

import "net/http"

func (h *Handlers) GetOrder(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    o, err := h.svc.GetOrder(r.Context(), id)
    if err != nil {
        respondDomainError(w, err)
        return
    }
    writeJSON(w, http.StatusOK, toOrderResponse(o))
}

order/presentation/http/routes.go:

package http

import "net/http"

func (h *Handlers) Register(mux *http.ServeMux) {
    mux.HandleFunc("POST /v1/orders", h.PlaceOrder)
    mux.HandleFunc("GET /v1/orders/{id}", h.GetOrder)
}

respondDomainError maps ErrOrderNotFound → 404, the two validation errors → 400,
and everything else → 500 with a generic mask. Stage 10 adds one case: the catalog
contract's ErrProductNotFound → 400.

Verify

go build ./...

Builds. The routes aren't reachable until the module is wired - next section.

Wire and observe

go run .

Place an order with any product_id and a price you choose. At this stage the
order service cannot validate the product against the catalog:

curl -s -X POST http://localhost:8080/v1/orders \
  -d '{"user_id":"u_1","items":[{"product_id":"p_1","name":"Widget","unit_price_cents":1,"quantity":100}]}'

{"id":"...","user_id":"u_1","items":[{"product_id":"p_1","name":"Widget","unit_price_cents":1,"quantity":100,"line_total_cents":100}],"total_cents":100,"created_at":"..."}

(Your id and created_at differ - they're generated.)

The math is exact: 100 units at 1 cent is 100 cents. The price is the problem. The
order domain has no way to ask the catalog whether p_1 exists or what it costs, so
it accepts both the product ID and the price in the request. A client can order a
hundred bags of beans for one dollar - the order domain trusts a price it did not
compute.

The obvious shortcut - import "minimart/catalog/application" from the order code -
is the wrong fix, and stage 09 explains why it is forbidden. Stage 09 publishes a
contract; stage 10 has the order service consume it, so prices come from the catalog
and the caller can no longer set them.

Create order/module.go:

package order

import (
    "context"
    "net/http"

    "minimart/order/application"
    "minimart/order/infrastructure/memory"
    orderhttp "minimart/order/presentation/http"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
)

type Module struct {
    svc      *application.Service
    handlers *orderhttp.Handlers
}

var _ module.Module = (*Module)(nil)

func NewModule() *Module { return &Module{} }

func (m *Module) Name() string { return "order" }

func (m *Module) Init(ctx context.Context) error {
    repo := memory.New()
    m.svc = application.NewService(repo)
    m.handlers = orderhttp.NewHandlers(m.svc)
    return nil
}

// RegisterContracts is a no-op: the order domain publishes no contract of its own.
// In stage 10 the order module starts *consuming* the catalog contract - but it
// still registers none.
func (m *Module) RegisterContracts(ctx context.Context, c *contracts.Contracts) error {
    return nil
}

func (m *Module) RegisterHTTP(ctx context.Context, mux *http.ServeMux) error {
    m.handlers.Register(mux)
    return nil
}

Stage 10 changes NewModule() to take the shared registry, so the service can reach
the catalog. For now it takes nothing.

In main.go, add the order module to the slice:

    modules := []module.Module{
        catalog.NewModule(),
        order.NewModule(),
    }

and add "minimart/order" to the imports. That is the whole cost of a new domain at
the composition root: one line and an import.

What you learned

A second domain is the same drill: domain → port → adapter → use cases → edge → module.
Package short names repeat across domains; import paths keep them distinct.
Trusting the client for prices is a coupling the next two stages remove.

Publish a Contract

The forbidden import

The order service needs a product's price. The shortcut is one import:

import "minimart/catalog/application" // don't

It compiles. That is the danger. With it, the order domain now depends on the
catalog's concrete service, its domain types, and its errors - its entire inner
world. Two domains that were separate are now welded: you cannot change the
catalog's internals without risking the order code, and you cannot test order
without dragging the whole catalog in. Later, if orders and catalog ever need to
call each other, the mutual import becomes a compile-time cycle Go refuses outright.

The rule:

A domain may never import another domain's application/, domain/, or
infrastructure/. It may import only the other domain's published contract.

A contract is a tiny package a domain exposes for others to call: one interface,
plain data types, published errors - nothing else. It is the domain's front door.
Everything behind it stays private and free to change.

Nothing in the compiler enforces this - the forbidden import builds fine. It is a
discipline (and, in production, a custom linter that fails the build on a
cross-domain import into anything but a client package).

The later sections build the catalog's contract; stage 10 has the order domain consume
it.

This is why a modular monolith is a useful training ground. Splitting code into
microservices does not fix muddy boundaries; it only adds a network to them. A
published contract gives you the same discipline while refactoring is still cheap.

The client package

The contract lives at catalog/presentation/module/client/. It is the only part of
the catalog other domains may import. It holds no entities, no service, no
infrastructure - only what a caller needs: the Catalog interface, a
dependency-free Product view, and a client-level ErrProductNotFound sentinel (so
callers never import the catalog's domain package for its errors).

It sits under presentation/ because it is another input adapter - a way the
outside (here, another module) drives the catalog - beside the HTTP edge.

Create catalog/presentation/module/client/client.go:

// Package client is the only part of the catalog domain other domains may import.
// It exposes the published contract interface and its plain data types - no
// entities, no application services, no infrastructure.
package client

import (
    "context"
    "errors"
)

// ErrProductNotFound is returned by the contract when no product has the given ID.
// It is a client-level sentinel so callers never import the catalog's domain package.
var ErrProductNotFound = errors.New("catalog: product not found")

// Catalog is the contract the catalog domain publishes to the rest of the system.
type Catalog interface {
    GetProduct(ctx context.Context, id string) (Product, error)
}

// Product is the dependency-free view of a catalog product passed across domains.
type Product struct {
    ID         string
    Name       string
    PriceCents int64
}

Product carries no JSON tags: it crosses a Go call boundary, not the wire. It is
deliberately separate from both domain.Product and the HTTP DTO, so each can
change without breaking the others. It also omits fields a caller doesn't need
(Stock, CreatedAt) - the contract exposes the minimum.

You now have three product shapes: the domain entity, the HTTP response, and this
cross-domain client.Product. They look similar because MiniMart is small, but they
serve different promises. If catalog later becomes a separate service, this contract
is the thing that turns into OpenAPI or protobuf; the order domain should not need to
learn catalog internals then either.

Verify

go build ./...

Builds. Nothing implements Catalog yet - that's next.

The adapter

The contract is an interface; something must satisfy it. That something is an adapter
in catalog/presentation/module - it holds the catalog's application service and
translates between domain types and the published client types. It is the bridge
from the front door to the domain's insides, and the only code that crosses that
line.

Create catalog/presentation/module/module.go:

// Package module adapts the catalog application service to the published
// client.Catalog contract. It is the only path other domains use to reach the
// catalog domain - they never touch its application, domain, or infrastructure.
package module

import (
    "minimart/catalog/application"
    "minimart/catalog/presentation/module/client"
)

// Catalog implements client.Catalog by delegating to the application service and
// translating domain types into the published client types.
type Catalog struct {
    svc *application.Service
}

// Compile-time proof this adapter satisfies the published contract.
var _ client.Catalog = (*Catalog)(nil)

func New(svc *application.Service) *Catalog {
    return &Catalog{svc: svc}
}

Create catalog/presentation/module/get_product.go:

package module

import (
    "context"
    "errors"

    "minimart/catalog/domain"
    "minimart/catalog/presentation/module/client"
)

// GetProduct is the cross-domain entry point. It calls the service, then maps the
// domain result and error into the published client types, so callers depend only
// on the client package.
func (c *Catalog) GetProduct(ctx context.Context, id string) (client.Product, error) {
    p, err := c.svc.GetProduct(ctx, id)
    if err != nil {
        if errors.Is(err, domain.ErrProductNotFound) {
            return client.Product{}, client.ErrProductNotFound
        }
        return client.Product{}, err
    }
    return client.Product{ID: p.ID, Name: p.Name, PriceCents: p.PriceCents}, nil
}

var _ client.Catalog = (*Catalog)(nil) proves the adapter satisfies the contract.
GetProduct calls the service, then maps the result: domain.Product →
client.Product, and domain.ErrProductNotFound → client.ErrProductNotFound.
Callers depend only on the client package - never on the catalog's domain.

Production note: an adapter like this can open an observability span before
calling the service, making cross-module hops visible on a request trace. It can
also wrap errors as they cross the boundary. The core shape remains: call, translate
types, translate errors.

Verify

go build ./...

Builds.

The registry

A caller shouldn't hunt down each domain's adapter. Instead, one shared registry
holds every published contract, and callers reach them all through it. Two types
work together:

Modules - the flat interface consumers depend on. It embeds each domain's contract, so calls read s.modules.GetProduct(...), not s.modules.Catalog.GetProduct(...).
Contracts - the concrete struct main.go builds and fills. Each module writes its adapter into its slot during RegisterContracts.

Struct for wiring, interface for consumption: main.go builds the concrete
Contracts, while application services depend on the Modules interface so tests
can pass a fake.

Verify() fails the boot if any slot was never filled - turning "someone forgot to
register" from a nil-pointer panic on the first request into a loud crash at startup.

Expand pkg/module/contracts/contracts.go from the empty stub of stage 07 into:

package contracts

import (
    "errors"

    catalog "minimart/catalog/presentation/module/client"
)

// Modules is the flat interface a domain calls other domains through. It embeds
// each domain's published contract, so callers write s.modules.GetProduct(...),
// not s.modules.Catalog.GetProduct(...).
//
// Application services depend on this INTERFACE (so tests can substitute a fake),
// while main.go builds the concrete *Contracts below.
type Modules interface {
    catalog.Catalog
}

// Contracts is the live registry that satisfies Modules. Each module writes its
// own adapter into its slot during the RegisterContracts phase. Because every
// module receives the same pointer, all slots are filled before any request runs.
type Contracts struct {
    catalog.Catalog
}

// Verify fails the boot if any contract slot was never filled. Calling it after
// RegisterContracts turns "someone forgot to register" from a nil-pointer panic
// on the first request into a loud crash at startup.
func (c *Contracts) Verify() error {
    if c.Catalog == nil {
        return errors.New("contracts: catalog not registered")
    }
    return nil
}

Go note: writing a type name alone inside a struct or interface is embedding.
In Contracts, embedding catalog.Catalog promotes its GetProduct method onto
Contracts; in the Modules interface, it merges the method set. That is what
makes cross-domain calls flat. An embedded interface field nobody assigns holds
nil, and calling through it panics - exactly the hole Verify plugs.

The import is aliased catalog (the last path element, client, would read
badly). Verify checks the one slot; each new published contract adds a field and a
matching check.

Verify

go build ./...

Builds - but main.go doesn't fill or verify the registry yet. That's the last section.

Four-phase boot

go run .

Products and orders still work. Now sabotage it: comment out the
c.Catalog = catalogmodule.New(m.svc) line in catalog/module.go (and the
catalogmodule import, which Go would flag as unused), then run again:

go run .
# boot: contracts: catalog not registered

The process refuses to start. Restore both lines. Without Verify(), that same
mistake would boot fine and, once stage 10 has the order domain consume the catalog,
nil-panic on the first order that needs the catalog - a failure at request time
instead of at boot.

Production note: check every dependency that can be verified before serving, including a database
ping, a required config value, a contract slot - is verified at boot for exactly
this reason: fail loudly at startup, not silently on a customer's first request.

Now the phases from stage 07 pay off. The catalog fills its registry slot in
RegisterContracts; main.go calls Verify() after every module has registered
and before any route is live. The order is load-bearing: contracts are published in
phase 2, checked in phase 3, and only in phase 4 do the doors open - so no request
can hit a half-wired registry.

Give catalog/module.go's RegisterContracts a real body, and add the catalogmodule import:

    catalogmodule "minimart/catalog/presentation/module"

// RegisterContracts publishes the catalog contract into the shared registry.
func (m *Module) RegisterContracts(ctx context.Context, c *contracts.Contracts) error {
    c.Catalog = catalogmodule.New(m.svc)
    return nil
}

In main.go, insert the Verify() gate between RegisterContracts and RegisterHTTP, so the loop now runs four phases:

    // Phase 3 - fail the boot now if any contract slot is still nil.
    if err := registry.Verify(); err != nil {
        log.Fatalf("boot: %v", err)
    }

Reference: the full four-phase main.go

package main

import (
    "context"
    "log"
    "net/http"

    "minimart/catalog"
    "minimart/order"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
)

func main() {
    ctx := context.Background()

    mux := http.NewServeMux()

    // /health lives in the composition root, not a domain: it answers "is this
    // process up?", an operational question, not a business capability.
    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        _, _ = w.Write([]byte(`{"status":"ok"}`))
    })

    // One registry pointer, shared by every module. Slots are empty now and
    // filled during RegisterContracts, before any request is served.
    registry := &amp;contracts.Contracts{}

    modules := []module.Module{
        catalog.NewModule(),
        order.NewModule(),
    }

    // Phase 1 - build each module's internals.
    for _, m := range modules {
        if err := m.Init(ctx); err != nil {
            log.Fatalf("init %s: %v", m.Name(), err)
        }
    }
    // Phase 2 - each module publishes its contract into the registry.
    for _, m := range modules {
        if err := m.RegisterContracts(ctx, registry); err != nil {
            log.Fatalf("register contracts %s: %v", m.Name(), err)
        }
    }
    // Phase 3 - fail the boot now if any contract slot is still nil.
    if err := registry.Verify(); err != nil {
        log.Fatalf("boot: %v", err)
    }
    // Phase 4 - wire HTTP routes.
    for _, m := range modules {
        if err := m.RegisterHTTP(ctx, mux); err != nil {
            log.Fatalf("register http %s: %v", m.Name(), err)
        }
    }

    log.Println("minimart listening on http://localhost:8080")
    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

(The order module still constructs with order.NewModule(); it consumes no contract
until stage 10, which changes that call to pass the registry.)

What you learned

A domain publishes a contract (interface + DTO + error) under presentation/module/client; nothing else may cross domains.
The shared registry is a struct to build and an interface to consume.
Verify() makes a forgotten registration a boot crash, not a runtime panic.

The Handshake

Consume a contract

The order service gains a second dependency: contracts.Modules. Note the type -
the interface, not the concrete *contracts.Contracts struct. A consumer depends
on the interface so a test can hand it a fake catalog; only main.go builds the
concrete registry.

There is a timing subtlety. The order module receives the registry pointer at
construction, while its slots are still empty (they fill during RegisterContracts
in phase 2). That is safe because the service only dereferences the registry at
request time - long after phase 3 has verified every slot is filled. One registry,
injected early, read late.

Because Modules embeds the catalog contract, the call reads flat:
s.modules.GetProduct(ctx, id), not s.modules.Catalog.GetProduct(...).

Rewrite order/application/service.go:

package application

import (
    "minimart/order/domain"
    "minimart/pkg/module/contracts"
)

// Service is the order application layer. It depends on the order repository port
// and on other domains through the contracts.Modules INTERFACE - never on their
// concrete packages. Depending on the interface is what lets tests pass a fake.
type Service struct {
    repo    domain.Repository
    modules contracts.Modules
}

func NewService(repo domain.Repository, modules contracts.Modules) *Service {
    return &Service{repo: repo, modules: modules}
}

Verify

go build ./order/application/...

The application package compiles. The whole binary is temporarily red - NewService
now needs a second argument that the order module supplies in the Cross-domain errors section. You finish
PlaceOrder next, then wire the registry through, then run it end to end.

Grows later: stage 12 adds a third argument - a Kafka publisher - so the
service can emit an OrderPlaced event after saving. The dependency stays an
interface, for the same reason modules is one.

Real prices

With the registry in hand, PlaceOrder fetches each product through the contract and
snapshots the catalog's name and price into the order item. The caller now sends only
a product ID and a quantity. A price the order domain did not compute is no longer
something it will accept.

That is more than validation; it is an authority decision. The client can request a
purchase, but the catalog owns the current price. The order owns the historical
snapshot once the order is placed. Naming who owns a fact is often the architecture.

Rewrite order/application/place_order.go:

package application

import (
    "context"
    "fmt"

    "minimart/order/domain"
)

// PlaceOrderRequest is the input to PlaceOrder. It carries NO prices or names:
// those are authoritative from the catalog, fetched below. The client only says
// which product and how many.
type PlaceOrderRequest struct {
    UserID string
    Items  []PlaceOrderItem
}

type PlaceOrderItem struct {
    ProductID string
    Quantity  int
}

// PlaceOrder resolves each product's real price from the catalog (through the
// published contract), builds the order, and saves it. The order domain trusts
// the catalog for prices, not the caller.
func (s *Service) PlaceOrder(ctx context.Context, req PlaceOrderRequest) (domain.Order, error) {
    if len(req.Items) == 0 {
        return domain.Order{}, domain.ErrNoItems
    }
    items := make([]domain.Item, 0, len(req.Items))
    for _, it := range req.Items {
        if it.Quantity <= 0 {
            return domain.Order{}, domain.ErrInvalidQuantity
        }
        p, err := s.modules.GetProduct(ctx, it.ProductID)
        if err != nil {
            return domain.Order{}, fmt.Errorf("resolve product %s: %w", it.ProductID, err)
        }
        items = append(items, domain.Item{
            ProductID:      p.ID,
            Name:           p.Name,
            UnitPriceCents: p.PriceCents,
            Quantity:       it.Quantity,
        })
    }
    order, err := domain.NewOrder(newID(), req.UserID, items)
    if err != nil {
        return domain.Order{}, err
    }
    if err := s.repo.Save(ctx, order); err != nil {
        return domain.Order{}, err
    }
    return order, nil
}

PlaceOrderItem loses Name and UnitPriceCents. Each item's price comes from
s.modules.GetProduct; a lookup failure is wrapped with %w, so the sentinel
survives for the edge to classify.

Strip the wire DTO in order/presentation/http/dto.go - placeOrderItem keeps only product_id and quantity:

// placeOrderRequest is the body of POST /v1/orders. Note there is no price field:
// the client cannot set prices. It only names products and quantities.
type placeOrderRequest struct {
    UserID string           `json:"user_id"`
    Items  []placeOrderItem `json:"items"`
}

type placeOrderItem struct {
    ProductID string `json:"product_id"`
    Quantity  int    `json:"quantity"`
}

(The response types - orderResponse, itemResponse, and toOrderResponse - are
unchanged from stage 08.)

Update the handler order/presentation/http/place_order.go to map only the two surviving fields:

func (h *Handlers) PlaceOrder(w http.ResponseWriter, r *http.Request) {
    var req placeOrderRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeJSON(w, http.StatusBadRequest, errorResponse{"invalid JSON body"})
        return
    }
    items := make([]application.PlaceOrderItem, 0, len(req.Items))
    for _, it := range req.Items {
        items = append(items, application.PlaceOrderItem{ProductID: it.ProductID, Quantity: it.Quantity})
    }
    o, err := h.svc.PlaceOrder(r.Context(), application.PlaceOrderRequest{
        UserID: req.UserID,
        Items:  items,
    })
    if err != nil {
        respondDomainError(w, err)
        return
    }
    writeJSON(w, http.StatusCreated, toOrderResponse(o))
}

Verify

go build ./order/application/... ./order/presentation/http/...

Green. The full binary goes green in the Cross-domain errors section, once the registry is threaded into the
order module.

Production note: teams often generate handlers from an OpenAPI specification,
letting the schema control which fields exist. Dropping a field here demonstrates
the same boundary without adding a generator to the course.

Cross-domain errors

go build ./... && go run .

Add a product and capture its generated id, then place an order with only IDs and
quantities:

PID=$(curl -s -X POST http://localhost:8080/v1/products \
  -d '{"name":"Widget","price_cents":500,"stock":10}' \
  | sed -n 's/.*"id":"\([a-f0-9]*\)".*/\1/p')

curl -s -X POST http://localhost:8080/v1/orders \
  -d "{\"user_id\":\"u_1\",\"items\":[{\"product_id\":\"$PID\",\"quantity\":2}]}"

The response's unit_price_cents and total_cents come from the catalog, not the
request - the client cannot set them. Now name a product that doesn't exist:

curl -s -i -X POST http://localhost:8080/v1/orders \
  -d '{"user_id":"u_1","items":[{"product_id":"ghost","quantity":1}]}' | head -1
# → HTTP/1.1 400 Bad Request

A product ID the caller named that doesn't exist is a bad request - the caller's
input was wrong - not a 404 on the order resource. The order edge already owns error
translation; it gains one case for the catalog contract's ErrProductNotFound. This
is why the same "not found" is a 404 on GET /v1/products/{id} but a 400 during order
placement: only the edge has the context to decide what a failure means.

Then the wiring: the order module takes the shared registry and passes it into the
service, and main.go hands it over at construction.

Add the catalog case to order/presentation/http/response.go:

package http

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

    catalogclient "minimart/catalog/presentation/module/client"
    "minimart/order/domain"
)

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

type errorResponse struct {
    Error string `json:"error"`
}

// respondDomainError maps order-domain errors AND the catalog contract's
// ErrProductNotFound to HTTP status codes. A product the caller named that does
// not exist is a bad request (the caller's input was wrong), not a 404 on the
// order resource.
func respondDomainError(w http.ResponseWriter, err error) {
    switch {
    case errors.Is(err, domain.ErrOrderNotFound):
        writeJSON(w, http.StatusNotFound, errorResponse{err.Error()})
    case errors.Is(err, domain.ErrNoItems),
        errors.Is(err, domain.ErrInvalidQuantity),
        errors.Is(err, catalogclient.ErrProductNotFound):
        writeJSON(w, http.StatusBadRequest, errorResponse{err.Error()})
    default:
        writeJSON(w, http.StatusInternalServerError, errorResponse{"internal error"})
    }
}

That catalogclient import is an order file reaching into catalog/… - legal
because the path is presentation/module/client, the one published package.

Rewrite order/module.go to receive and pass the registry:

package order

import (
    "context"
    "net/http"

    "minimart/order/application"
    "minimart/order/infrastructure/memory"
    orderhttp "minimart/order/presentation/http"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
)

// Module wires the order domain. It holds the shared contracts registry so its
// service can call other domains through it.
type Module struct {
    registry *contracts.Contracts
    svc      *application.Service
    handlers *orderhttp.Handlers
}

var _ module.Module = (*Module)(nil)

// NewModule receives the shared registry pointer. Its slots are empty now and
// filled during RegisterContracts, before any request runs - so it is safe to
// stash here and call later from request handlers.
func NewModule(registry *contracts.Contracts) *Module {
    return &Module{registry: registry}
}

func (m *Module) Name() string { return "order" }

func (m *Module) Init(ctx context.Context) error {
    repo := memory.New()
    m.svc = application.NewService(repo, m.registry)
    m.handlers = orderhttp.NewHandlers(m.svc)
    return nil
}

// RegisterContracts is a no-op: the order domain publishes no contract of its own
// (nothing else calls into it) - it only consumes the catalog contract.
func (m *Module) RegisterContracts(ctx context.Context, c *contracts.Contracts) error {
    return nil
}

func (m *Module) RegisterHTTP(ctx context.Context, mux *http.ServeMux) error {
    m.handlers.Register(mux)
    return nil
}

The *contracts.Contracts pointer satisfies the contracts.Modules interface, so
handing it to NewService is where concrete becomes abstract - exactly once, at the
boundary between wiring and business logic.

Grows later: this order/module.go reaches its final shape over stages 11-12

Postgres pools replace the in-memory repo (stage 11) and a Kafka publisher plus a RegisterWorkers method are added (stage 12). Each changes only NewModule's signature and Init's body; the domain and application layers stay put. Likewise main.go is replaced by the server/worker/migrate subcommands in stage 13.

In main.go, pass the registry to the order module:

    modules := []module.Module{
        catalog.NewModule(),
        order.NewModule(registry),
    }

(The catalog still takes no registry; it publishes a contract but consumes none.)

What you learned

Consumers depend on the Modules interface; only main.go builds the concrete registry.
The registry pointer is injected empty at construction and read at request time, after Verify.
The same domain error becomes different HTTP statuses at different edges - the edge decides meaning.

Real Storage: Postgres

Postgres in Docker

The in-memory adapter forgets everything on restart. From here you replace it with
Postgres - but the swap comes last. First stand up the database and give the service
a place to read its connection string.

Configuration lives in one package, conf. Every value comes from an environment
variable with a default that targets the local compose stack, so the service runs
with no .env file in development. Two database DSNs matter:

DATABASE_URL - the primary (read-write) database. Writes go here.
DATABASE_REPLICA_URL - a read replica. Reads go here. Unset, it falls back to the primary - the common case locally, where there is only one database.

The read/write split is shaped now so the adapter can route reads to a replica later
without any layer above learning of it - the same forward-shaping that put ctx in
the port back in stage 03.

Create docker-compose.yml with the database service (a Kafka broker joins it in stage 12):

# Local development dependencies. Postgres is added now; Redpanda joins in stage 12.
# Run `docker compose up -d`, then run the app on your host. the **Swap the engine** section shows a
# temporary `main.go`; stage 13 adds the `server` subcommand and shows how to add
# the app itself as a service.

services:
  db:
    image: postgres:16-alpine
    container_name: minimart-db
    environment:
      POSTGRES_USER: minimart
      POSTGRES_PASSWORD: minimart
      POSTGRES_DB: minimart
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U minimart"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  pgdata:

The named pgdata volume is what makes the data survive docker compose down - and
what will make the restart test in the Swap the engine section mean something.

Create conf/environment.go. The database settings are used now; HTTPAddr is used when cmd/server.go appears in the **Swap the engine section, and KafkaBrokers is added in stage 12:**

// Package conf reads all configuration from environment variables in one place.
// Defaults target the local docker-compose stack, so the service runs with no
// .env file in development. In production every value comes from the environment.
package conf

import (
    "os"
)

func env(key, def string) string {
    if v := os.Getenv(key); v != "" {
        return v
    }
    return def
}

// DatabaseURL is the primary (read-write) Postgres DSN. Writes go here.
func DatabaseURL() string {
    return env("DATABASE_URL", "postgres://minimart:minimart@localhost:5432/minimart?sslmode=disable")
}

// DatabaseReplicaURL is the read-replica DSN. Reads go here. It falls back to the
// primary when unset - the common case in local development, where there is only
// one database.
func DatabaseReplicaURL() string {
    if v := os.Getenv("DATABASE_REPLICA_URL"); v != "" {
        return v
    }
    return DatabaseURL()
}

// HTTPAddr is the address the HTTP server listens on.
func HTTPAddr() string {
    return env("HTTP_ADDR", ":8080")
}

// Env identifies the deployment environment for logs or environment-specific
// behavior at the edges.
func Env() string {
    return env("ENV", "development")
}

Record the same knobs in sample.env, so operators know what to set (defaults already match compose, so the file is optional locally):

HTTP_ADDR=":8080"
ENV="development"

# Primary (read-write) Postgres. Reads use DATABASE_REPLICA_URL if set, else this.
DATABASE_URL="postgres://minimart:minimart@localhost:5432/minimart?sslmode=disable"
# DATABASE_REPLICA_URL="postgres://minimart:minimart@localhost:5433/minimart?sslmode=disable"

Start the database:

docker compose up -d

Production note: a useful convention is to give each configurable value one
environment variable and document it in sample.env. Adding a setting then means
updating both conf and sample.env, rather than burying a string literal in code.

Verify

docker compose exec db psql -U minimart -c '\dt'

Did not find any relations.

Postgres is up and reachable, and the schema is empty - you create the tables next.

Migrations

Resolve the new dependency. The subcommand dispatcher does not exist until stage 13,
so run the migrator from a temporary main.go for this check:

package main

import "minimart/cmd"

func main() {
    if err := cmd.RunMigrate(); err != nil {
        panic(err)
    }
}

go mod tidy          # pulls dbmate; writes go.sum
go run .
docker compose exec db psql -U minimart -c '\dt'

                List of relations
 Schema |       Name        | Type  |  Owner
--------+-------------------+-------+----------
 public | order_items       | table | minimart
 public | orders            | table | minimart
 public | products          | table | minimart
 public | schema_migrations | table | minimart

schema_migrations is dbmate's own bookkeeping table - it records which migrations
have run, so a second go run . with this temporary entry point is a no-op. Restore
your course main.go before continuing.

The database is empty. The schema is not something you type into psql by hand - it
is versioned SQL, checked into the repo, applied the same way in every
environment. The tool is dbmate: each migration is a file with an up block (how
to apply it) and a down block (how to undo it), named with a UTC timestamp so files
sort into apply order.

MiniMart runs dbmate as a library, not the CLI, so the same binary that serves
traffic can also run minimart migrate. That is the whole point of a schema that
lives in code: deploys apply it as a one-shot step (stage 13).

Create db/migrations/20240101000001_create_products.sql:

-- migrate:up
CREATE TABLE products (
    id          TEXT        PRIMARY KEY,
    name        TEXT        NOT NULL,
    price_cents BIGINT      NOT NULL,
    stock       INT         NOT NULL DEFAULT 0,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- migrate:down
DROP TABLE IF EXISTS products;

The literal -- migrate:up and -- migrate:down comments are how dbmate splits the
file: everything under up runs on apply, everything under down runs on rollback.
price_cents is BIGINT - the database mirrors the domain's int64 cents.

Create db/migrations/20240101000002_create_orders.sql:

-- migrate:up
CREATE TABLE orders (
    id          TEXT        PRIMARY KEY,
    user_id     TEXT        NOT NULL,
    total_cents BIGINT      NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE order_items (
    id               BIGSERIAL PRIMARY KEY,
    order_id         TEXT      NOT NULL REFERENCES orders (id),
    product_id       TEXT      NOT NULL,
    name             TEXT      NOT NULL,
    unit_price_cents BIGINT    NOT NULL,
    quantity         INT       NOT NULL,
    line_total_cents BIGINT    NOT NULL
);

CREATE INDEX order_items_order_id_idx ON order_items (order_id);

-- migrate:down
DROP TABLE IF EXISTS order_items;
DROP TABLE IF EXISTS orders;

Go note: the course hard-codes the timestamps (20240101000001, …) so every
learner ends up with the same files. In real work you run dbmate new create_widgets,
which stamps the current UTC time - never invent a timestamp by hand.

Create the migration runner db/db.go:

// Package db applies schema migrations using dbmate as a library (not the CLI),
// so the same binary that serves traffic can also run `minimart migrate`.
package db

import (
    "fmt"
    "net/url"

    "github.com/amacneil/dbmate/v2/pkg/dbmate"
    _ "github.com/amacneil/dbmate/v2/pkg/driver/postgres" // registers the postgres driver

    "minimart/conf"
)

type Migrator struct {
    m *dbmate.DB
}

// New builds a Migrator pointed at the primary database. dbmate looks for
// migration files in ./db/migrations by default.
func New() (*Migrator, error) {
    u, err := url.Parse(conf.DatabaseURL())
    if err != nil {
        return nil, fmt.Errorf("parse DATABASE_URL: %w", err)
    }
    m := dbmate.New(u)
    m.AutoDumpSchema = false // don't write a schema.sql dump; migrations are the source of truth
    return &Migrator{m: m}, nil
}

// Migrate creates the database if it does not exist, then applies every pending
// migration in timestamp order. It is safe to run on every deploy.
func (mig *Migrator) Migrate() error {
    if err := mig.m.CreateAndMigrate(); err != nil {
        return fmt.Errorf("create and migrate: %w", err)
    }
    return nil
}

Expose it as a subcommand entry point, cmd/migrate.go:

package cmd

import "minimart/db"

// RunMigrate applies all pending schema migrations, then exits. Deploys run this
// as a one-shot step before starting the server.
func RunMigrate() error {
    m, err := db.New()
    if err != nil {
        return err
    }
    return m.Migrate()
}

The cmd package (server / worker / migrate) fills in over the next stages; stage 13
adds the dispatcher that turns RunMigrate into minimart migrate.

sqlc

You could write the SQL and the row-scanning by hand, but scanning is repetitive and
easy to get subtly wrong. sqlc does it for you: you write the queries in a
.sql file, annotate each with the shape it returns, and sqlc generate emits
type-safe Go - structs for each row, a method per query.

Two rules make this safe:

sqlc reads the schema from db/migrations (the same files dbmate applies), so the generated code and the real database can never drift. Rename a column in a migration and the next sqlc generate changes the Go accordingly.
The generated packages are not yours to edit. Change the .sql, regenerate.

Each domain gets a reader package and a writer package - the read/replica vs.
primary split from the Postgres in Docker section, expressed as two generated packages.

Create sqlc.yaml at the project root:

version: "2"

# Each domain gets a separate reader and writer package, generated from that
# domain's queries.sql. The schema source of truth is the dbmate migrations, so
# sqlc and the database can never drift. Regenerate with `sqlc generate`.
# Never hand-edit the generated *.sql.go / models.go / db.go files.
sql:
  - engine: "postgresql"
    schema: "db/migrations"
    queries: "catalog/infrastructure/postgres/reader/queries.sql"
    gen:
      go: &go
        package: "reader"
        out: "catalog/infrastructure/postgres/reader"
        sql_package: "pgx/v5"
        emit_pointers_for_null_types: true

  - engine: "postgresql"
    schema: "db/migrations"
    queries: "catalog/infrastructure/postgres/writer/queries.sql"
    gen:
      go:
        <<: *go
        package: "writer"
        out: "catalog/infrastructure/postgres/writer"

  - engine: "postgresql"
    schema: "db/migrations"
    queries: "order/infrastructure/postgres/reader/queries.sql"
    gen:
      go:
        <<: *go
        package: "reader"
        out: "order/infrastructure/postgres/reader"

  - engine: "postgresql"
    schema: "db/migrations"
    queries: "order/infrastructure/postgres/writer/queries.sql"
    gen:
      go:
        <<: *go
        package: "writer"
        out: "order/infrastructure/postgres/writer"

Write the catalog's read queries, catalog/infrastructure/postgres/reader/queries.sql:

-- name: GetProduct :one
SELECT id, name, price_cents, stock, created_at, updated_at
FROM products
WHERE id = $1;

-- name: ListProducts :many
SELECT id, name, price_cents, stock, created_at, updated_at
FROM products
ORDER BY created_at;

The -- name: X :kind annotation is the contract with sqlc. :one generates a method
returning a single row, :many a slice, and :exec (next) a method returning only an
error. $1 is Postgres's positional parameter.

Write the catalog's write query, catalog/infrastructure/postgres/writer/queries.sql:

-- name: SaveProduct :exec
INSERT INTO products (id, name, price_cents, stock)
VALUES ($1, $2, $3, $4)
ON CONFLICT (id) DO UPDATE
SET name        = EXCLUDED.name,
    price_cents = EXCLUDED.price_cents,
    stock       = EXCLUDED.stock,
    updated_at  = NOW();

ON CONFLICT ... DO UPDATE is the upsert that lets one SaveProduct method serve both
create and update - matching the port's single Save.

The order domain needs its own two files, since sqlc.yaml lists all four. order/infrastructure/postgres/reader/queries.sql:

-- name: GetOrder :one
SELECT id, user_id, total_cents, created_at
FROM orders
WHERE id = $1;

-- name: ListOrderItems :many
SELECT product_id, name, unit_price_cents, quantity, line_total_cents
FROM order_items
WHERE order_id = $1
ORDER BY id;

And order/infrastructure/postgres/writer/queries.sql:

-- name: CreateOrder :exec
INSERT INTO orders (id, user_id, total_cents)
VALUES ($1, $2, $3);

-- name: CreateOrderItem :exec
INSERT INTO order_items (order_id, product_id, name, unit_price_cents, quantity, line_total_cents)
VALUES ($1, $2, $3, $4, $5, $6);

Generate:

sqlc generate

This writes three files into each of the four out directories - db.go,
models.go, and queries.sql.go - the packages the adapter imports. They do not
exist until you run this; that is why a fresh checkout must sqlc generate before it
builds.

Production note: teams should pin the sqlc version in the Makefile and CI so
developers regenerate byte-identical code. Committing generated directories also
lets normal builds run without code generation; only query changes require it.

Verify

ls catalog/infrastructure/postgres/reader

db.go  models.go  queries.sql.go

queries.sql.go holds a GetProduct method and a ProductsRow-style struct you did
not write. Open it if you like - then close it and never edit it.

The Postgres adapter

go build ./...

Compiles clean. The var _ domain.Repository lines are doing the real checking here -
if a method signature drifts from the port, the build fails at exactly that line,
naming the missing method.

sqlc gives you type-safe queries; the adapter is the thin layer that maps between the
generated row types and your domain entities, and that satisfies the domain's
Repository port. This is the only new code you write for storage - the port is
unchanged, so nothing above it moves.

Generated rows are not domain entities. They are database shapes: column names,
nullable fields, integer widths, and join results. Mapping them by hand is the same
boundary discipline as DTO mapping in stage 05 - a little duplication that keeps a
schema change from becoming a domain change.

Two adapter jobs are worth naming:

Error translation. The driver returns pgx.ErrNoRows for a missing row; the adapter turns that into the domain's ErrProductNotFound, so the application layer never learns which database is underneath.
Atomic writes. An order is a row in orders plus rows in order_items. They must all land or none - a transaction, entirely inside the adapter.

Each adapter opens with var _ domain.Repository = (*T)(nil) - the compile-time proof
that it fits the port. That single line is why the swap in the Swap the engine section is safe.

Create catalog/infrastructure/postgres/catalog_repository.go:

package postgres

import (
    "context"
    "errors"

    "github.com/jackc/pgx/v5"
    "github.com/jackc/pgx/v5/pgxpool"

    "minimart/catalog/domain"
    "minimart/catalog/infrastructure/postgres/reader"
    "minimart/catalog/infrastructure/postgres/writer"
)

// CatalogRepository implements the catalog domain.Repository port over Postgres.
// It holds sqlc query objects bound to a read pool and a write pool.
type CatalogRepository struct {
    reader *reader.Queries
    writer *writer.Queries
}

// Compile-time proof the Postgres adapter satisfies the same port as the
// in-memory one. This is why swapping storage touches no business code.
var _ domain.Repository = (*CatalogRepository)(nil)

func NewCatalogRepository(readPool, writePool *pgxpool.Pool) *CatalogRepository {
    return &CatalogRepository{
        reader: reader.New(readPool),
        writer: writer.New(writePool),
    }
}

func (r *CatalogRepository) Save(ctx context.Context, p domain.Product) error {
    return r.writer.SaveProduct(ctx, writer.SaveProductParams{
        ID:         p.ID,
        Name:       p.Name,
        PriceCents: p.PriceCents,
        Stock:      int32(p.Stock),
    })
}

func (r *CatalogRepository) GetByID(ctx context.Context, id string) (domain.Product, error) {
    row, err := r.reader.GetProduct(ctx, id)
    if err != nil {
        // Translate the driver's "no rows" into the domain's not-found error, so
        // the application layer never learns which database we use.
        if errors.Is(err, pgx.ErrNoRows) {
            return domain.Product{}, domain.ErrProductNotFound
        }
        return domain.Product{}, err
    }
    return domain.Product{
        ID:         row.ID,
        Name:       row.Name,
        PriceCents: row.PriceCents,
        Stock:      int(row.Stock),
    }, nil
}

func (r *CatalogRepository) List(ctx context.Context) ([]domain.Product, error) {
    rows, err := r.reader.ListProducts(ctx)
    if err != nil {
        return nil, err
    }
    out := make([]domain.Product, 0, len(rows))
    for _, row := range rows {
        out = append(out, domain.Product{
            ID:         row.ID,
            Name:       row.Name,
            PriceCents: row.PriceCents,
            Stock:      int(row.Stock),
        })
    }
    return out, nil
}

Reads use r.reader (the replica pool), writes use r.writer (the primary). The
int32(p.Stock) / int(row.Stock) conversions bridge the domain's int and Postgres's
32-bit INT - the adapter's job, kept out of the domain.

Create order/infrastructure/postgres/order_repository.go - the same shape, but Save is a transaction:

package postgres

import (
    "context"
    "errors"

    "github.com/jackc/pgx/v5"
    "github.com/jackc/pgx/v5/pgxpool"

    "minimart/order/domain"
    "minimart/order/infrastructure/postgres/reader"
    "minimart/order/infrastructure/postgres/writer"
)

type OrderRepository struct {
    writePool *pgxpool.Pool
    reader    *reader.Queries
    writer    *writer.Queries
}

var _ domain.Repository = (*OrderRepository)(nil)

func NewOrderRepository(readPool, writePool *pgxpool.Pool) *OrderRepository {
    return &OrderRepository{
        writePool: writePool,
        reader:    reader.New(readPool),
        writer:    writer.New(writePool),
    }
}

// Save writes the order and all its items in one transaction. If any item insert
// fails, the deferred Rollback undoes the whole thing.
func (r *OrderRepository) Save(ctx context.Context, o domain.Order) error {
    tx, err := r.writePool.Begin(ctx)
    if err != nil {
        return err
    }
    defer tx.Rollback(ctx) // no-op after a successful Commit

    q := r.writer.WithTx(tx)
    if err := q.CreateOrder(ctx, writer.CreateOrderParams{
        ID:         o.ID,
        UserID:     o.UserID,
        TotalCents: o.TotalCents,
    }); err != nil {
        return err
    }
    for _, it := range o.Items {
        if err := q.CreateOrderItem(ctx, writer.CreateOrderItemParams{
            OrderID:        o.ID,
            ProductID:      it.ProductID,
            Name:           it.Name,
            UnitPriceCents: it.UnitPriceCents,
            Quantity:       int32(it.Quantity),
            LineTotalCents: it.LineTotalCents,
        }); err != nil {
            return err
        }
    }
    return tx.Commit(ctx)
}

func (r *OrderRepository) GetByID(ctx context.Context, id string) (domain.Order, error) {
    row, err := r.reader.GetOrder(ctx, id)
    if err != nil {
        if errors.Is(err, pgx.ErrNoRows) {
            return domain.Order{}, domain.ErrOrderNotFound
        }
        return domain.Order{}, err
    }
    items, err := r.reader.ListOrderItems(ctx, id)
    if err != nil {
        return domain.Order{}, err
    }
    domItems := make([]domain.Item, 0, len(items))
    for _, it := range items {
        domItems = append(domItems, domain.Item{
            ProductID:      it.ProductID,
            Name:           it.Name,
            UnitPriceCents: it.UnitPriceCents,
            Quantity:       int(it.Quantity),
            LineTotalCents: it.LineTotalCents,
        })
    }
    return domain.Order{
        ID:         row.ID,
        UserID:     row.UserID,
        TotalCents: row.TotalCents,
        Items:      domItems,
        CreatedAt:  row.CreatedAt,
    }, nil
}

r.writer.WithTx(tx) returns a query set bound to the transaction, so both inserts run
inside it. defer tx.Rollback(ctx) is the safety net: it is a no-op once Commit
succeeds, and undoes everything if any insert returns early.

Production note: a repeated multi-table write like this can be factored into a
WithinTransaction(ctx, func(ctx) error) error port method, so a use case can
declare "these writes succeed together" while the adapter supplies the
BEGIN/COMMIT. For read-modify-write rules, another common shape is
UpdateProduct(ctx, id, func(Product) (Product, error)): the use case names the
change, and the adapter owns locking, retry, and commit. The decision crosses the
port; the SQL never does.

Swap the engine

The subcommand dispatcher (minimart server) arrives in stage 13. Until then, run the
server from a one-line temporary main.go:

package main

import "minimart/cmd"

func main() {
    if err := cmd.StartServer(); err != nil {
        panic(err)
    }
}

With Postgres up and migrated (from the Postgres in Docker section and the Migrations section):

go run .

In a second terminal, create a product and read it back (note the id):

curl -s -X POST localhost:8080/v1/products \
  -d '{"name":"Widget","price_cents":1299,"stock":10}'

curl -s localhost:8080/v1/products

Now the proof memory could never give you. Stop the server (Ctrl+C), start it
again, and list products:

go run .
# second terminal:
curl -s localhost:8080/v1/products

The product is still there. The process lost its memory; the data was never in the
process.

The change surface. Files touched to swap the entire storage engine:

domain/ - 0
application/ - 0
presentation/ - 0
catalog/module.go and order/module.go - one function (Init) and the constructor
new adapters + generated code under infrastructure/postgres/

The Dependency Rule was never about folder names. This is the number it buys.

Everything is in place: the schema, the generated queries, the adapters. The swap
itself is one line in each module's Init - the single place that names a concrete
adapter - plus wiring the connection pools at the composition root and handing them in.

Count what does not change: domain/, application/, presentation/. The port never
moved, so nothing that depends on the port moved. That is the guarantee this whole
architecture exists to deliver, and you are about to measure it.

Everything in this section is storage only - no Kafka. The composition root gains its
event wiring in stage 12; here it stays exactly as small as stage 09 left it.

In catalog/module.go, Init builds the Postgres adapter instead of memory.New(), and NewModule now receives the two pools:

// Package catalog wires the catalog domain into the modular monolith. It is the
// domain's composition root: the one place that names concrete adapters.
package catalog

import (
    "context"
    "net/http"

    "github.com/jackc/pgx/v5/pgxpool"

    "minimart/catalog/application"
    "minimart/catalog/infrastructure/postgres"
    cataloghttp "minimart/catalog/presentation/http"
    catalogmodule "minimart/catalog/presentation/module"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
)

// Module is the catalog domain's self-wiring unit.
type Module struct {
    readPool  *pgxpool.Pool
    writePool *pgxpool.Pool
    svc       *application.Service
    handlers  *cataloghttp.Handlers
}

var _ module.Module = (*Module)(nil)

func NewModule(readPool, writePool *pgxpool.Pool) *Module {
    return &Module{readPool: readPool, writePool: writePool}
}

func (m *Module) Name() string { return "catalog" }

// Init chooses the concrete storage adapter. Swapping storage is this one line;
// no other layer is touched. (Earlier stages used memory.New() here.)
func (m *Module) Init(ctx context.Context) error {
    repo := postgres.NewCatalogRepository(m.readPool, m.writePool)
    m.svc = application.NewService(repo)
    m.handlers = cataloghttp.NewHandlers(m.svc)
    return nil
}

func (m *Module) RegisterContracts(ctx context.Context, c *contracts.Contracts) error {
    c.Catalog = catalogmodule.New(m.svc)
    return nil
}

func (m *Module) RegisterHTTP(ctx context.Context, mux *http.ServeMux) error {
    m.handlers.Register(mux)
    return nil
}

The same swap in order/module.go - Postgres repo, pools in the constructor. Its service still takes two arguments (repository + registry); the publisher joins in stage 12:

package order

import (
    "context"
    "net/http"

    "github.com/jackc/pgx/v5/pgxpool"

    "minimart/order/application"
    "minimart/order/infrastructure/postgres"
    orderhttp "minimart/order/presentation/http"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
)

type Module struct {
    registry  *contracts.Contracts
    readPool  *pgxpool.Pool
    writePool *pgxpool.Pool
    svc       *application.Service
    handlers  *orderhttp.Handlers
}

var _ module.Module = (*Module)(nil)

func NewModule(registry *contracts.Contracts, readPool, writePool *pgxpool.Pool) *Module {
    return &Module{registry: registry, readPool: readPool, writePool: writePool}
}

func (m *Module) Name() string { return "order" }

func (m *Module) Init(ctx context.Context) error {
    repo := postgres.NewOrderRepository(m.readPool, m.writePool)
    m.svc = application.NewService(repo, m.registry)
    m.handlers = orderhttp.NewHandlers(m.svc)
    return nil
}

func (m *Module) RegisterContracts(ctx context.Context, c *contracts.Contracts) error { return nil }

func (m *Module) RegisterHTTP(ctx context.Context, mux *http.ServeMux) error {
    m.handlers.Register(mux)
    return nil
}

The pools are shared infrastructure, so the composition root builds them. Create cmd/deps.go:

package cmd

import (
    "context"
    "fmt"

    "github.com/jackc/pgx/v5/pgxpool"

    "minimart/conf"
)

// newPools builds a read pool (replica) and a write pool (primary). Locally both
// DSNs resolve to the same database; in production they point at different hosts.
func newPools(ctx context.Context) (readPool, writePool *pgxpool.Pool, err error) {
    writePool, err = pgxpool.New(ctx, conf.DatabaseURL())
    if err != nil {
        return nil, nil, fmt.Errorf("connect primary: %w", err)
    }
    readPool, err = pgxpool.New(ctx, conf.DatabaseReplicaURL())
    if err != nil {
        writePool.Close()
        return nil, nil, fmt.Errorf("connect replica: %w", err)
    }
    return readPool, writePool, nil
}

Wire it in cmd/server.go - build the pools, then pass them to the modules:

package cmd

import (
    "context"
    "log"
    "net/http"

    "minimart/catalog"
    "minimart/conf"
    "minimart/order"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
)

// StartServer runs the HTTP API. It builds the DB pools, then runs the four-phase
// module boot and serves.
func StartServer() error {
    ctx := context.Background()

    readPool, writePool, err := newPools(ctx)
    if err != nil {
        return err
    }
    defer writePool.Close()
    defer readPool.Close()

    mux := http.NewServeMux()
    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        _, _ = w.Write([]byte(`{"status":"ok"}`))
    })

    registry := &contracts.Contracts{}
    modules := []module.Module{
        catalog.NewModule(readPool, writePool),
        order.NewModule(registry, readPool, writePool),
    }

    for _, m := range modules {
        if err := m.Init(ctx); err != nil {
            return err
        }
    }
    for _, m := range modules {
        if err := m.RegisterContracts(ctx, registry); err != nil {
            return err
        }
    }
    if err := registry.Verify(); err != nil {
        return err
    }
    for _, m := range modules {
        if err := m.RegisterHTTP(ctx, mux); err != nil {
            return err
        }
    }

    log.Printf("minimart server listening on %s", conf.HTTPAddr())
    return http.ListenAndServe(conf.HTTPAddr(), mux)
}

The boot loop is unchanged from stage 09. The only new lines are the two newPools
calls and the pools passed into each NewModule.

Grows in stage 12: this server.go and both module.go files reach their final
form in stage 12, which adds the Kafka producer (server.go), the publisher (order
module + service), and a RegisterWorkers method (the Module interface and every
module). Stage 11 is storage only.

What you learned

A new storage engine is a new adapter plus one line at each swap point - the port never moves, so nothing above it does.
Migrations (dbmate) own the schema; sqlc generates type-safe queries from it; the adapter maps generated rows to domain entities and translates driver errors.
The composition root owns shared infrastructure (connection pools) and injects it; the module only assembles.

Events with Kafka

Why events

When an order is placed, other parts of the system want to react: send a
confirmation, start fulfilment, update a dashboard. You could call each of them
directly from PlaceOrder - but then the order domain would import every domain that
cares, and grow a new import every time another one does. That is the stage-08
coupling problem, back at a larger scale.

The decoupled answer is a published event. After the order is saved, the order
domain announces a fact - an order was placed - to a broker, and returns. It does
not know or care who listens. Consumers subscribe independently and react on their own
time. Adding a new reaction adds a new consumer; the order domain never changes.

Two properties come with this:

Decoupling. The publisher depends on nothing downstream. Reactions are added and removed without touching the code that emits the event.
Asynchrony. The reaction runs after the response is sent, in a separate process, so a slow email never slows down checkout.

Now the structural claim that makes this fit everything you have already built. A Kafka
consumer is a function:

func(msg []byte) error

It receives raw transport bytes, deserializes them into a request, and calls an
application service. That is exactly what an HTTP handler does - read the request
body, decode JSON, call the service. The transport differs (a topic instead of a
socket); the shape is identical. So a message consumer is a first-class input
adapter, and it lives where every input adapter lives: presentation/. Not a special
category - the same hexagon, a second kind of door.

The publisher side is the mirror image: an output port, an interface the
application depends on, with a Kafka adapter behind it - the same pattern as the
repository port and its Postgres adapter.

Production note: an application can run many of these consumers across domains,
with each consumer sitting beside its domain's HTTP handlers in
presentation/message/event/. They remain ordinary input adapters; that is the point.

Redpanda

You need a broker to publish to and consume from. Redpanda speaks the Kafka
protocol in a single container with no ZooKeeper and no JVM, which makes it ideal
locally - the app talks to it with the same Kafka client libraries it would use against
a real Kafka cluster. Add it beside Postgres in compose, and add one config knob for
the broker address.

Add the redpanda service to docker-compose.yml, under services: beside db:

  redpanda:
    image: redpandadata/redpanda:v24.2.18
    container_name: minimart-redpanda
    command:
      - redpanda
      - start
      - --mode=dev-container
      - --kafka-addr=PLAINTEXT://0.0.0.0:9092
      - --advertise-kafka-addr=PLAINTEXT://localhost:9092
    ports:
      - "9092:9092"

--mode=dev-container runs a single-node broker tuned for local development - no
replication, no auth. --advertise-kafka-addr=PLAINTEXT://localhost:9092 is the
address the broker hands back to clients, so a client on your host connects to
localhost:9092.

Add the broker address to conf/environment.go (it belongs to the same config file you started in the **Postgres in Docker section). Add strings to the import block:**

// KafkaBrokers is the comma-separated list of Kafka bootstrap brokers.
func KafkaBrokers() []string {
    return strings.Split(env("KAFKA_BROKERS", "localhost:9092"), ",")
}

And the matching line in sample.env:

# Kafka bootstrap brokers (comma-separated). Redpanda speaks the Kafka protocol.
KAFKA_BROKERS="localhost:9092"

Bring the broker up:

docker compose up -d

Production note: a deployed broker may be a managed multi-node cluster, with
KAFKA_BROKERS containing comma-separated bootstrap hosts. It may also require
SASL/SCRAM and TLS. Those are omitted locally because Redpanda's development mode
runs unauthenticated; the application boundary stays the same.

Verify

docker compose ps

Both minimart-db and minimart-redpanda show as running (Up). If your image
includes the admin tools, you can also list topics - empty for now:

docker compose exec redpanda rpk topic list
# (no topics yet)

Topics are created on first publish in the later sections, so an empty list here is
expected.

The producer

The application must emit events without depending on Kafka. So the publisher is an
output port - a small interface the application imports - with a concrete Kafka
implementation behind it. Exactly the repository pattern, one layer over.

Three pieces:

Topics and consumer groups - named constants, so nothing spells a topic wrong.
The event payload - a plain struct with JSON tags, a published contract like an HTTP response body: small, stable, changed only in backward-compatible ways.
The Publisher interface + Producer - the port the app depends on, and the sarama/watermill adapter that satisfies it.

Create pkg/kafka/topics.go:

// Package kafka is MiniMart's thin wrapper over sarama + watermill. Domains depend
// only on the small Publisher interface and the func(msg []byte) error consumer
// signature - never on sarama or watermill directly.
package kafka

// Topic is a Kafka topic name.
type Topic string

func (t Topic) String() string { return string(t) }

// Topics used by MiniMart.
const (
    OrderPlacedTopic Topic = "order-placed"
)

// Consumer groups. Two different groups subscribed to the same topic EACH receive
// every message - that is how one published event fans out to several independent
// handlers. Here one OrderPlaced event drives both an order-side confirmation and
// a notification email.
const (
    OrderConfirmationConsumer = "order-confirmation"
    NotificationConsumer      = "order-notification"
)

Two consumer-group names on one topic is the setup for fan-out - you wire both in the worker section.

Create the event payload pkg/message/events.go:

// Package message holds the event payloads published across domains. An event is
// a published contract, like an HTTP response body: keep it small and stable, and
// change it only in backward-compatible ways.
package message

// OrderPlaced is emitted after an order is successfully saved. Consumers in other
// domains react to it without the order domain knowing they exist.
type OrderPlaced struct {
    OrderID    string `json:"order_id"`
    UserID     string `json:"user_id"`
    TotalCents int64  `json:"total_cents"`
    ItemCount  int    `json:"item_count"`
}

Create pkg/kafka/producer.go - the port and its implementation:

package kafka

import (
    "context"
    "encoding/json"
    "fmt"

    "github.com/IBM/sarama"
    "github.com/ThreeDotsLabs/watermill"
    wkafka "github.com/ThreeDotsLabs/watermill-kafka/v3/pkg/kafka"
    "github.com/ThreeDotsLabs/watermill/message"
)

// Publisher is the output port the application depends on to emit events. The
// application imports this interface, not sarama - so a test can pass a fake.
type Publisher interface {
    PublishMessage(ctx context.Context, topic Topic, key string, payload interface{}) error
}

// Producer is the Kafka implementation of Publisher.
type Producer struct {
    pub message.Publisher
}

func NewProducer(brokers []string) (*Producer, error) {
    cfg := wkafka.DefaultSaramaSyncPublisherConfig()
    // V2_1_0_0 keeps the client on non-flexible protocol encodings, which every
    // Kafka-compatible broker (including Redpanda in dev mode) accepts.
    cfg.Version = sarama.V2_1_0_0

    pub, err := wkafka.NewPublisher(
        wkafka.PublisherConfig{
            Brokers:               brokers,
            Marshaler:             wkafka.NewWithPartitioningMarshaler(partitionByKey),
            OverwriteSaramaConfig: cfg,
        },
        watermill.NewStdLogger(false, false),
    )
    if err != nil {
        return nil, fmt.Errorf("new kafka publisher: %w", err)
    }
    return &Producer{pub: pub}, nil
}

// partitionByKey sends all messages sharing a key to the same partition, so events
// for one order stay ordered.
func partitionByKey(topic string, msg *message.Message) (string, error) {
    return msg.Metadata.Get("key"), nil
}

func (p *Producer) PublishMessage(ctx context.Context, topic Topic, key string, payload interface{}) error {
    var body []byte
    switch v := payload.(type) {
    case []byte:
        body = v
    default:
        var err error
        body, err = json.Marshal(payload)
        if err != nil {
            return fmt.Errorf("marshal event: %w", err)
        }
    }
    msg := message.NewMessage(watermill.NewUUID(), body)
    msg.SetContext(ctx)
    msg.Metadata.Set("key", key)
    if err := p.pub.Publish(topic.String(), msg); err != nil {
        return fmt.Errorf("publish to %s: %w", topic, err)
    }
    return nil
}

func (p *Producer) Close() error { return p.pub.Close() }

The key (the order ID) routes all of one order's messages to the same partition, so
they stay ordered. PublishMessage accepts structs for normal JSON events and raw
[]byte for dead-letter forwarding, where the original payload must not be JSON-encoded
a second time. The important line is the interface: the application will depend on
Publisher, so a test hands it a fake and never touches a broker (stage 14).

Verify

go mod tidy      # resolves sarama + watermill; updates go.sum
go build ./pkg/...

The pkg/kafka and pkg/message packages compile. Nothing calls PublishMessage yet

the order service starts publishing in the Publish on place section.

Publish on place

The order service gains a third dependency: the kafka.Publisher port. Like the
repository and the contracts registry, it is an interface, injected - so a test
passes a fake and the service never touches a real broker.

Publishing happens after the order is committed, and it is best-effort: the order
already exists, so a broker hiccup must not fail a request. The service logs the
failure and returns success. This is a deliberate trade-off - you will see its stronger
alternative below.

Add the publisher field to order/application/service.go; NewService gains a third parameter:

package application

import (
    "minimart/order/domain"
    "minimart/pkg/kafka"
    "minimart/pkg/module/contracts"
)

// Service is the order application layer. It depends on the order repository port,
// on other domains through the contracts.Modules INTERFACE, and on the Kafka
// Publisher INTERFACE - never on concrete infrastructure. Depending on interfaces
// is what lets tests pass fakes for all three.
type Service struct {
    repo      domain.Repository
    modules   contracts.Modules
    publisher kafka.Publisher
}

func NewService(repo domain.Repository, modules contracts.Modules, publisher kafka.Publisher) *Service {
    return &Service{repo: repo, modules: modules, publisher: publisher}
}

Add the publish call at the end of order/application/place_order.go, after the save:

package application

import (
    "context"
    "fmt"
    "log"

    "minimart/order/domain"
    "minimart/pkg/kafka"
    "minimart/pkg/message"
)

// PlaceOrderRequest is the input to PlaceOrder. It carries NO prices or names:
// those are authoritative from the catalog, fetched below. The client only says
// which product and how many.
type PlaceOrderRequest struct {
    UserID string
    Items  []PlaceOrderItem
}

type PlaceOrderItem struct {
    ProductID string
    Quantity  int
}

// PlaceOrder resolves each product's real price from the catalog (through the
// published contract), builds and saves the order, then publishes an OrderPlaced
// event for other domains to react to.
func (s *Service) PlaceOrder(ctx context.Context, req PlaceOrderRequest) (domain.Order, error) {
    if len(req.Items) == 0 {
        return domain.Order{}, domain.ErrNoItems
    }
    items := make([]domain.Item, 0, len(req.Items))
    for _, it := range req.Items {
        if it.Quantity <= 0 {
            return domain.Order{}, domain.ErrInvalidQuantity
        }
        p, err := s.modules.GetProduct(ctx, it.ProductID)
        if err != nil {
            return domain.Order{}, fmt.Errorf("resolve product %s: %w", it.ProductID, err)
        }
        items = append(items, domain.Item{
            ProductID:      p.ID,
            Name:           p.Name,
            UnitPriceCents: p.PriceCents,
            Quantity:       it.Quantity,
        })
    }
    order, err := domain.NewOrder(newID(), req.UserID, items)
    if err != nil {
        return domain.Order{}, err
    }
    if err := s.repo.Save(ctx, order); err != nil {
        return domain.Order{}, err
    }

    // The order is committed. Publishing is best-effort: a broker hiccup must not
    // fail a request whose order already exists, so we log and continue. (A system
    // needing an at-least-once guarantee writes the event to a transactional outbox
    // in the same DB transaction and relays it separately.)
    if err := s.publisher.PublishMessage(ctx, kafka.OrderPlacedTopic, order.ID, message.OrderPlaced{
        OrderID:    order.ID,
        UserID:     order.UserID,
        TotalCents: order.TotalCents,
        ItemCount:  len(order.Items),
    }); err != nil {
        log.Printf("order %s: publish %s failed: %v", order.ID, kafka.OrderPlacedTopic, err)
    }
    return order, nil
}

The order ID is the partition key (second argument), keeping one order's events
ordered. Everything before the save is unchanged from stage 10.

Production note: best-effort publish can drop an event if the broker is down at
exactly the wrong moment. When the reaction must not be lost, use the transactional
outbox: write the event into an outbox table inside the same transaction that
saves the order, then a relay process reads the table and publishes - so the event
and the order commit atomically. The publish call moves; the handler on the other
side does not care which delivery path fed it.

Verify

go build ./order/...

The order application layer compiles against the new three-argument NewService. The
whole binary is temporarily red - the order module still calls NewService with two
arguments; the worker section threads the publisher through. You build the consumers first.

The consumer

A consumer handler is func(msg []byte) error: deserialize the JSON, call an
application service, return. It knows nothing about Kafka - the same way an HTTP
handler knows nothing about sockets. It lives in presentation/message/event/, beside
the domain's HTTP handlers.

You write two consumers of the same event, to make fan-out concrete:

The order domain consumes its own event (a normal pattern - a follow-up step like starting fulfilment).
A new notification domain, worker-only: no HTTP, no contract, it exists purely to react.

order/presentation/message/event/order_placed.go - the order-side handler:

// Package event holds the order domain's own message input adapters. Consuming an
// event your own domain published is a normal pattern - here it stands in for a
// follow-up step like starting fulfilment.
package event

import (
    "encoding/json"
    "log"

    "minimart/pkg/message"
)

type Handler struct{}

func NewHandler() *Handler { return &Handler{} }

// OrderConfirmation reacts to the order-placed topic. It logs a confirmation; a
// real system might reserve stock or start fulfilment.
func (h *Handler) OrderConfirmation(msg []byte) error {
    var event message.OrderPlaced
    if err := json.Unmarshal(msg, &event); err != nil {
        return err
    }
    log.Printf("[order] confirming order %s for user %s (%d cents, %d items)",
        event.OrderID, event.UserID, event.TotalCents, event.ItemCount)
    return nil
}

order/presentation/message/workers.go - declares which handler subscribes to which topic and group:

package message

import (
    "context"

    "minimart/order/presentation/message/event"
    "minimart/pkg/kafka"
    "minimart/pkg/worker"
)

// Workers registers the order domain's Kafka consumers onto the worker.
func Workers(ctx context.Context, w *worker.Worker) {
    h := event.NewHandler()
    w.AttachKafka(ctx, kafka.OrderPlacedTopic, kafka.OrderConfirmationConsumer, h.OrderConfirmation)
}

Now the notification domain. Its application service, notification/application/service.go:

// Package application is the notification domain's use-case layer. In a real
// system it would send email or push notifications; here it logs, standing in for
// any side effect a downstream domain performs in reaction to an event.
package application

import (
    "context"
    "log"
)

type Service struct{}

func NewService() *Service { return &Service{} }

func (s *Service) SendOrderConfirmation(ctx context.Context, orderID, userID string, totalCents int64) error {
    log.Printf("[notification] emailing user %s: order %s confirmed, total %d cents",
        userID, orderID, totalCents)
    return nil
}

Its input adapter, notification/presentation/message/event/order_placed.go - note it is structurally identical to the order one, and to an HTTP controller:

// Package event holds the notification domain's message input adapters. A handler
// here is structurally identical to an HTTP controller: it deserializes a transport
// payload (JSON bytes off a Kafka topic) into a request and calls the application
// service. It knows nothing about Kafka.
package event

import (
    "context"
    "encoding/json"

    "minimart/notification/application"
    "minimart/pkg/message"
)

type Handler struct {
    svc *application.Service
}

func NewHandler(svc *application.Service) *Handler { return &Handler{svc: svc} }

// OrderPlaced is the input adapter for the order-placed topic.
func (h *Handler) OrderPlaced(msg []byte) error {
    var event message.OrderPlaced
    if err := json.Unmarshal(msg, &event); err != nil {
        return err
    }
    return h.svc.SendOrderConfirmation(context.Background(), event.OrderID, event.UserID, event.TotalCents)
}

Its workers.go - same topic, a different consumer group:

package message

import (
    "context"

    "minimart/notification/application"
    "minimart/notification/presentation/message/event"
    "minimart/pkg/kafka"
    "minimart/pkg/worker"
)

// Workers registers the notification domain's Kafka consumers onto the worker.
func Workers(ctx context.Context, w *worker.Worker, svc *application.Service) {
    h := event.NewHandler(svc)
    w.AttachKafka(ctx, kafka.OrderPlacedTopic, kafka.NotificationConsumer, h.OrderPlaced)
}

The module, notification/module.go - a worker-only domain:

package notification

import (
    "context"
    "net/http"

    "minimart/notification/application"
    "minimart/notification/presentation/message"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
    "minimart/pkg/worker"
)

// Module is a worker-only domain: it registers no HTTP routes and publishes no
// contract. It exists to react to events, demonstrating that a consumer is a
// first-class input adapter.
type Module struct {
    svc *application.Service
}

var _ module.Module = (*Module)(nil)

func NewModule() *Module { return &Module{} }

func (m *Module) Name() string { return "notification" }

func (m *Module) Init(ctx context.Context) error {
    m.svc = application.NewService()
    return nil
}

func (m *Module) RegisterContracts(ctx context.Context, c *contracts.Contracts) error { return nil }

func (m *Module) RegisterHTTP(ctx context.Context, mux *http.ServeMux) error { return nil }

func (m *Module) RegisterWorkers(ctx context.Context, w *worker.Worker) error {
    message.Workers(ctx, w, m.svc)
    return nil
}

RegisterHTTP is a no-op, RegisterWorkers does the work - the mirror of catalog,
which registers HTTP and skips workers. Same interface, different doors.

Verify

go build ./order/presentation/message/event ./notification/application ./notification/presentation/message/event

The pure handlers compile. The workers.go files and notification/module.go
reference pkg/worker, which is created in the worker section, so those files compile with the full
tree after the worker runtime exists.

The worker

Bring up the stack, migrate, then run both processes. The dispatcher that turns
these into go run . server / go run . worker arrives in stage 13, so for now use
small temporary main.go files that call cmd.RunMigrate, cmd.StartWorker, or
cmd.StartServer directly:

docker compose up -d
go run .            # with main calling cmd.RunMigrate
go run .            # terminal 1, with main calling cmd.StartWorker
go run .            # terminal 2, with main calling cmd.StartServer

In a third terminal, create a product and place an order:

PID=$(curl -s -XPOST localhost:8080/v1/products \
  -d '{"name":"Widget","price_cents":500,"stock":10}' \
  | sed -n 's/.*"id":"\([a-f0-9]*\)".*/\1/p')

curl -s -XPOST localhost:8080/v1/orders \
  -d "{\"user_id\":\"u1\",\"items\":[{\"product_id\":\"$PID\",\"quantity\":2}]}"

Watch the worker terminal - one order, two log lines from two consumer groups:

[order] confirming order <order-id> for user u1 (1000 cents, 1 items)
[notification] emailing user u1: order <order-id> confirmed, total 1000 cents

One published event, two independent reactions. Adding a third is a third consumer
group - the order domain never learns it exists.

The handlers from the consumer section need a runtime. Two pieces provide it:

pkg/kafka/consumer.go - subscribes a consumer group to a topic and calls a handler per message, with a dead-letter fallback.
pkg/worker/worker.go - the worker-process equivalent of an http.ServeMux: modules attach handlers to it during a new boot phase, RegisterWorkers.

That new phase is added to the Module interface, and a cmd/worker.go boots the same
modules the server does but runs phase 4b (workers) instead of 4a (HTTP). Because
OrderPlacedTopic has two consumer groups, one published event is delivered to
both - fan-out.

pkg/kafka/consumer.go:

package kafka

import (
    "context"
    "fmt"

    "github.com/IBM/sarama"
    "github.com/ThreeDotsLabs/watermill"
    wkafka "github.com/ThreeDotsLabs/watermill-kafka/v3/pkg/kafka"
)

// Consumer subscribes to topics and dispatches raw message bodies to handlers.
type Consumer struct {
    brokers []string
    dlq     Publisher // optional; failed messages are routed here
    logger  watermill.LoggerAdapter
}

func NewConsumer(brokers []string, dlq Publisher) *Consumer {
    return &Consumer{
        brokers: brokers,
        dlq:     dlq,
        logger:  watermill.NewStdLogger(false, false),
    }
}

// Subscribe joins consumerGroup on topic and calls handler for each message body.
// It blocks until ctx is cancelled. The handler signature - func(msg []byte) error
// - is deliberately the same shape as reading an HTTP request body: a queue message
// is just another input.
//
// A handler error routes the message to a dead-letter topic (<topic>.dlq) if a DLQ
// publisher is configured, then acknowledges it so one poison message cannot block
// the partition forever.
func (c *Consumer) Subscribe(ctx context.Context, topic Topic, consumerGroup string, handler func(msg []byte) error) error {
    cfg := wkafka.DefaultSaramaSubscriberConfig()
    // Same version pin as the producer - see producer.go.
    cfg.Version = sarama.V2_1_0_0
    cfg.Consumer.Offsets.Initial = sarama.OffsetOldest

    sub, err := wkafka.NewSubscriber(
        wkafka.SubscriberConfig{
            Brokers:               c.brokers,
            Unmarshaler:           wkafka.DefaultMarshaler{},
            OverwriteSaramaConfig: cfg,
            ConsumerGroup:         consumerGroup,
        },
        c.logger,
    )
    if err != nil {
        return fmt.Errorf("new kafka subscriber: %w", err)
    }
    defer sub.Close()

    messages, err := sub.Subscribe(ctx, topic.String())
    if err != nil {
        return fmt.Errorf("subscribe %s: %w", topic, err)
    }

    for msg := range messages {
        if err := handler(msg.Payload); err != nil {
            c.logger.Error("handler failed; routing to DLQ", err, watermill.LogFields{
                "topic": topic.String(), "group": consumerGroup,
            })
            if c.dlq != nil {
                _ = c.dlq.PublishMessage(ctx, Topic(topic.String()+".dlq"), msg.Metadata.Get("key"), msg.Payload)
            }
        }
        msg.Ack()
    }
    return nil
}

The consumer group is the fan-out mechanism: each group gets its own copy of every
message, so two groups on one topic means two deliveries.

pkg/worker/worker.go:

// Package worker runs a domain's Kafka consumers. It is the worker-process
// equivalent of an http.ServeMux: modules register handlers onto it during the
// RegisterWorkers boot phase, and each handler runs as one consumer-group loop.
package worker

import (
    "context"
    "log"
    "sync"

    "minimart/pkg/kafka"
)

type Worker struct {
    consumer *kafka.Consumer
    producer kafka.Publisher
    wg       sync.WaitGroup
}

func New(consumer *kafka.Consumer, producer kafka.Publisher) *Worker {
    return &Worker{consumer: consumer, producer: producer}
}

// Producer exposes the shared publisher to modules that also emit events.
func (w *Worker) Producer() kafka.Publisher { return w.producer }

// AttachKafka registers one consumer: a handler for a topic under a consumer
// group. Each runs in its own goroutine until ctx is cancelled.
func (w *Worker) AttachKafka(ctx context.Context, topic kafka.Topic, group string, handler func(msg []byte) error) {
    w.wg.Add(1)
    go func() {
        defer w.wg.Done()
        if err := w.consumer.Subscribe(ctx, topic, group, handler); err != nil {
            log.Printf("worker: %s/%s stopped: %v", topic, group, err)
        }
    }()
}

// Wait blocks until every consumer goroutine has exited.
func (w *Worker) Wait() { w.wg.Wait() }

Add RegisterWorkers to the Module interface, pkg/module/module.go:

package module

import (
    "context"
    "net/http"

    "minimart/pkg/module/contracts"
    "minimart/pkg/worker"
)

// Module is one self-contained domain in the modular monolith.
//
// The boot sequence in cmd/ calls these methods in phases, for every module:
//
//  1. Init             build the module's own internals (service, adapters).
//  2. RegisterContracts publish this module's contract into the shared registry.
//  3. (Verify)         the boot fails if any contract slot is still nil.
//     4a. RegisterHTTP    (server) wire this module's routes onto the mux.
//     4b. RegisterWorkers (worker) wire this module's Kafka consumers onto the worker.
//
// The server process runs phase 4a; the worker process runs phase 4b. No module
// may call another module before phase 3 completes.
type Module interface {
    Name() string
    Init(ctx context.Context) error
    RegisterContracts(ctx context.Context, c *contracts.Contracts) error
    RegisterHTTP(ctx context.Context, mux *http.ServeMux) error
    RegisterWorkers(ctx context.Context, w *worker.Worker) error
}

Every module now implements it: catalog's is a no-op (added next), notification's
registers its consumer (the consumer section), and the order module registers its own - while also
finally taking the Kafka publisher.

Add the no-op to catalog/module.go. Its Init and constructor are unchanged from the **Swap the engine section; it only gains this method (and the minimart/pkg/worker import) to satisfy the wider interface:**

// RegisterWorkers is a no-op: the catalog domain has no Kafka consumers.
func (m *Module) RegisterWorkers(ctx context.Context, w *worker.Worker) error { return nil }

order/module.go - the order domain's final composition root:

package order

import (
    "context"
    "net/http"

    "github.com/jackc/pgx/v5/pgxpool"

    "minimart/order/application"
    "minimart/order/infrastructure/postgres"
    orderhttp "minimart/order/presentation/http"
    ordermessage "minimart/order/presentation/message"
    "minimart/pkg/kafka"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
    "minimart/pkg/worker"
)

// Module wires the order domain. It holds the shared contracts registry (to call
// other domains), the DB pools, and the Kafka publisher.
type Module struct {
    registry  *contracts.Contracts
    readPool  *pgxpool.Pool
    writePool *pgxpool.Pool
    publisher kafka.Publisher
    svc       *application.Service
    handlers  *orderhttp.Handlers
}

var _ module.Module = (*Module)(nil)

func NewModule(registry *contracts.Contracts, readPool, writePool *pgxpool.Pool, publisher kafka.Publisher) *Module {
    return &Module{registry: registry, readPool: readPool, writePool: writePool, publisher: publisher}
}

func (m *Module) Name() string { return "order" }

func (m *Module) Init(ctx context.Context) error {
    repo := postgres.NewOrderRepository(m.readPool, m.writePool)
    m.svc = application.NewService(repo, m.registry, m.publisher)
    m.handlers = orderhttp.NewHandlers(m.svc)
    return nil
}

// RegisterContracts is a no-op: the order domain publishes no contract of its own.
func (m *Module) RegisterContracts(ctx context.Context, c *contracts.Contracts) error { return nil }

func (m *Module) RegisterHTTP(ctx context.Context, mux *http.ServeMux) error {
    m.handlers.Register(mux)
    return nil
}

// RegisterWorkers wires the order domain's Kafka consumers.
func (m *Module) RegisterWorkers(ctx context.Context, w *worker.Worker) error {
    ordermessage.Workers(ctx, w)
    return nil
}

cmd/worker.go - the worker process. It is the server's boot with phase 4b in place of 4a:

package cmd

import (
    "context"
    "log"

    "minimart/catalog"
    "minimart/conf"
    "minimart/notification"
    "minimart/order"
    kafkapkg "minimart/pkg/kafka"
    "minimart/pkg/module"
    "minimart/pkg/module/contracts"
    "minimart/pkg/worker"
)

// StartWorker runs the background consumers. It boots the same modules as the
// server, but wires their Kafka handlers (RegisterWorkers) instead of HTTP routes,
// then blocks while the consumer goroutines run.
func StartWorker() error {
    ctx := context.Background()

    readPool, writePool, err := newPools(ctx)
    if err != nil {
        return err
    }
    defer writePool.Close()
    defer readPool.Close()

    producer, err := kafkapkg.NewProducer(conf.KafkaBrokers())
    if err != nil {
        return err
    }
    defer producer.Close()

    // The producer doubles as the dead-letter publisher for failed messages.
    consumer := kafkapkg.NewConsumer(conf.KafkaBrokers(), producer)
    w := worker.New(consumer, producer)

    registry := &contracts.Contracts{}
    modules := []module.Module{
        catalog.NewModule(readPool, writePool),
        order.NewModule(registry, readPool, writePool, producer),
        notification.NewModule(),
    }

    for _, m := range modules {
        if err := m.Init(ctx); err != nil {
            return err
        }
    }
    for _, m := range modules {
        if err := m.RegisterContracts(ctx, registry); err != nil {
            return err
        }
    }
    if err := registry.Verify(); err != nil {
        return err
    }
    for _, m := range modules {
        if err := m.RegisterWorkers(ctx, w); err != nil {
            return err
        }
    }

    log.Println("minimart worker started; consuming events")
    w.Wait()
    return nil
}

The notification module joins the module list here (the server does not need it - it
has no HTTP). Same four-phase boot, same Verify gate; only the final phase differs.

Give cmd/server.go the producer too. The HTTP path publishes OrderPlaced when an order is placed, so the server also builds a producer and passes it to order.NewModule. Add to StartServer (from the **Swap the engine section), with the import kafkapkg "minimart/pkg/kafka":**

    // after building the pools:
    producer, err := kafkapkg.NewProducer(conf.KafkaBrokers())
    if err != nil {
        return err
    }
    defer producer.Close()

    // ...and pass it into the order module:
    order.NewModule(registry, readPool, writePool, producer),

Both processes now build a producer: the server publishes on order placement, the
worker consumes (and reuses it as the dead-letter publisher).

What you learned

A message consumer is an input adapter: func(msg []byte) error, deserialize and call a service, ignorant of the transport.
The publisher is an output port; the application depends on the Publisher interface, with a Kafka adapter behind it.
One event fans out to many handlers via distinct consumer groups - decoupling the emitter from every reaction.
The server and worker are the same modules booted through different final phases.

Ship It

Subcommands

go build -o minimart .
./minimart
# usage: minimart <server|worker|migrate>

./minimart nope
# unknown command "nope"; want server|worker|migrate

Both error paths exit non-zero (echo $? shows 2). With the stack up (next section),
./minimart migrate, ./minimart server, and ./minimart worker each run their role.

You have three entry functions - StartServer, StartWorker, RunMigrate - but no
front door that chooses between them. One binary with three roles is the standard
deployment shape: the same image runs as an HTTP server, a background worker, or a
one-shot migration, and the platform picks which by the command argument.

main does nothing but hand off. A small dispatcher in cmd reads os.Args[1] and
calls the matching function. No framework - a switch.

main.go shrinks to a single call:

package main

import "minimart/cmd"

// The whole program is three subcommands (server, worker, migrate) behind one
// binary. main just hands off to cmd.Execute, which dispatches on os.Args.
func main() {
    cmd.Execute()
}

cmd/root.go is the dispatcher:

// Package cmd holds the three entry points of the single MiniMart binary.
// One binary, three roles - the deployment platform chooses which by the command
// argument (server, worker, or migrate). A plain switch keeps the course free of
// an additional command-framework dependency.
package cmd

import (
    "fmt"
    "os"
)

func Execute() {
    if len(os.Args) < 2 {
        fmt.Fprintln(os.Stderr, "usage: minimart <server|worker|migrate>")
        os.Exit(2)
    }

    var err error
    switch os.Args[1] {
    case "server":
        err = StartServer()
    case "worker":
        err = StartWorker()
    case "migrate":
        err = RunMigrate()
    default:
        fmt.Fprintf(os.Stderr, "unknown command %q; want server|worker|migrate\n", os.Args[1])
        os.Exit(2)
    }

    if err != nil {
        fmt.Fprintln(os.Stderr, "fatal:", err)
        os.Exit(1)
    }
}

A missing or unknown command exits 2 (usage error); a failure from a role exits 1.
Those exit codes are what an orchestrator reads to decide a container is unhealthy.

Production note: a command framework such as cobra can add flags, help text,
and nested commands. The basic shape stays the same: main calls Execute, and
Execute dispatches. A plain switch is enough for this course.

The Dockerfile

go mod tidy                 # ensure go.sum exists and is current
docker build -t minimart .
docker images minimart

The build completes and docker images shows a minimart image in the tens of
megabytes, not hundreds. Sanity-check the entry point:

docker run --rm minimart nope
# unknown command "nope"; want server|worker|migrate

The container ran the binary and hit the dispatcher from the Subcommands section. (Running server or
migrate needs the database reachable - that is the next section.)

A Go binary is self-contained, so the runtime image needs almost nothing - no compiler,
no source, no module cache. A multi-stage build gets you there: one stage compiles
with the full Go toolchain, the next copies only the binary (and the migrations) into a
tiny base. The result is a few megabytes instead of hundreds.

Two details matter:

The build needs go.sum. It is produced by go mod tidy, which must run before docker build so the file exists to copy in.
The migrations ship inside the image, so minimart migrate works in any environment without mounting files.

Create Dockerfile at the project root:

# syntax=docker/dockerfile:1

# --- Build stage: compile a static binary ---
FROM golang:1.22-alpine AS build
WORKDIR /app

# Cache dependencies first. go.sum is produced by `go mod tidy` - run it before
# building the image.
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /minimart .

# --- Run stage: a tiny image with just the binary and the migrations ---
FROM alpine:3.20
WORKDIR /app
COPY --from=build /minimart /app/minimart
# The migrations ship in the image so `minimart migrate` works in any environment.
COPY --from=build /app/db /app/db

EXPOSE 8080

# One binary, three roles. The platform picks the role via the command argument;
# CMD defaults to the HTTP server.
ENTRYPOINT ["/app/minimart"]
CMD ["server"]

COPY go.mod go.sum ./ before the rest is a layer-caching trick: dependencies re-download
only when those files change, not on every source edit. CGO_ENABLED=0 makes a static
binary that runs on the bare alpine image with no C library. The ENTRYPOINT +
CMD split means docker run minimart defaults to server, while docker run minimart worker overrides the argument - the same three roles from the Subcommands section.

Run the stack

Bring the stack up and apply migrations:

make compose        # or: docker compose up -d
make migrate        # or: go run . migrate

Run the two processes (separate terminals):

make server         # terminal 1 - HTTP API on :8080
make worker         # terminal 2 - background consumers

Now exercise it end to end - health, create a product, place an order priced from the
catalog:

curl localhost:8080/health
# {"status":"ok"}

PID=$(curl -s -XPOST localhost:8080/v1/products \
  -d '{"name":"Widget","price_cents":500,"stock":10}' \
  | sed -n 's/.*"id":"\([a-f0-9]*\)".*/\1/p')

curl -s -XPOST localhost:8080/v1/orders \
  -d "{\"user_id\":\"u1\",\"items\":[{\"product_id\":\"$PID\",\"quantity\":2}]}"
# total_cents is 1000 = 2 × 500, computed from the catalog price, not the client.

The worker terminal logs both reactions to the one order - the order-side
confirmation and the notification email. That is the whole system: HTTP in, event out,
two consumers reacting, all backed by Postgres.

Treat this as an end-to-end smoke check: it proves the deployed pieces can talk to
each other. It is not where you want to prove every business rule. Those stay in fast
unit tests and focused integration tests, which stage 14 adds.

Everything exists; this section runs it in order. The sequence is always the same:
infrastructure up, schema applied, then the processes. A Makefile captures the common
commands so nobody memorizes flags.

Create Makefile at the project root:

.PHONY: build server worker migrate test compose compose-down sqlc new-migration tidy

# Build the single binary.
build:
    go build -o minimart .

# Run each role locally (one binary, three subcommands).
server:
    go run . server

worker:
    go run . worker

migrate:
    go run . migrate

test:
    go test ./...

# Bring the local Postgres + Redpanda stack up / down.
compose:
    docker compose up -d

compose-down:
    docker compose down

# Regenerate the type-safe query code from queries.sql (needs the sqlc CLI).
sqlc:
    sqlc generate

# Create a new timestamped migration:  make new-migration name=create_widgets
new-migration:
    dbmate new $(name)

tidy:
    go mod tidy

Go note: Makefile recipes must be indented with a tab, not spaces - a
spaces-indented recipe fails with missing separator.

Deploy

The image from the Dockerfile section and the one-binary-three-roles shape from the Subcommands section are already deploy-ready.
The rest is operational discipline, and it all falls out of decisions you already made.

Deployment style is still not the architecture. The same hexagon can run on a VM,
Kubernetes, Cloud Run, or a laptop. Managed platforms solve scaling and process
supervision; they do not rescue tangled domain code.

One image, pushed to a registry. Build once, tag, push; every environment pulls the
same artifact.

TAG=registry.example.com/minimart:$(git rev-parse --short HEAD)
docker build -t "$TAG" .
docker push "$TAG"

Migrate as a one-shot release step. Run minimart migrate before rolling the new
server/worker, as its own job that must succeed first. It is idempotent and safe to
re-run (the Migrations section), so a retried deploy is harmless. Schema changes ship with the code that
needs them, in the same image.

Config from the environment. Every knob is an env var read in conf, with a
compose-friendly default (the Postgres in Docker section). Production sets DATABASE_URL, DATABASE_REPLICA_URL,
KAFKA_BROKERS, HTTP_ADDR, ENV - no code change between staging and prod, only
values. This is the twelve-factor rule; it is why nothing is a string literal.

Health checks. GET /health returns {"status":"ok"} with no dependencies, so a
load balancer or orchestrator can ask "is this process up?" cheaply and keep only live
instances in rotation. It lives in the composition root, not a domain - an operational
question, not a business one (stage 01).

Independent horizontal scaling. server and worker are the same binary, different
argument - so they scale separately. A traffic spike adds server replicas; a backlog of
events adds worker replicas. Consumer groups (the worker section) coordinate the workers: Kafka
distributes a topic's partitions across the replicas in a group, so adding a worker adds
throughput without double-processing.

A simple pipeline. The CI shape mirrors your local commands: run unit tests, bring
up compose dependencies, migrate, run the integration tests stage 14 adds, build the
image, push it, run the migration job, then roll server and worker. The provider
can change; the order of confidence should not.

Production note: a deployment can use one image, a migration job that gates
the rollout, environment-only config, /health for the load balancer, and server and
worker deployments scaled on different signals (request latency and consumer lag).

Prove It With Tests

The full testing map is bigger than this stage, but the boundaries are simple:

Kind	Proves	Uses
Unit	Business logic and orchestration	Fakes, no infrastructure
Integration	One adapter wired to a real dependency	Real Postgres, real migrations
Component	One service through its public adapter	HTTP plus real infra, other services faked
E2E smoke	The deployed pieces can talk	The running stack, few happy paths

Unit tests

go test ./order/application/

ok      minimart/order/application  0.004s

Green in milliseconds, with no server, database, or broker. Now trust the net - break
order/domain/order.go's line-total math to items[i].UnitPriceCents (drop the
* Quantity), rerun, watch want total 1250, got 750, then undo it. A suite you have
watched fail is a suite you can trust.

PlaceOrder is the most important code in MiniMart: it resolves prices across a domain
boundary, computes money, and publishes an event. It has three dependencies, and you
injected all three as interfaces - domain.Repository, contracts.Modules,
kafka.Publisher. So a test hands in tiny structs that satisfy them and controls every
input. These stand-ins are fakes, and they cost about thirty lines.

Because the ports are interfaces, faking them needs no framework. The test is
table-driven (stage 02's pattern at a harder job): happy path, empty order, unknown
product, bad quantity - plus an assertion on how many events were published.

All of this is one file, order/application/place_order_test.go.

The three fakes:

package application

import (
    "context"
    "errors"
    "testing"

    catalogclient "minimart/catalog/presentation/module/client"
    "minimart/order/domain"
    "minimart/pkg/kafka"
    "minimart/pkg/message"
)

// fakeRepo is a hand-written test double for the order Repository port.
type fakeRepo struct {
    saved   domain.Order
    saveErr error
}

func (f *fakeRepo) Save(ctx context.Context, o domain.Order) error {
    f.saved = o
    return f.saveErr
}
func (f *fakeRepo) GetByID(ctx context.Context, id string) (domain.Order, error) {
    return f.saved, nil
}

// fakeModules impersonates the entire catalog domain via the published contract.
type fakeModules struct {
    products map[string]catalogclient.Product
}

func (f *fakeModules) GetProduct(ctx context.Context, id string) (catalogclient.Product, error) {
    p, ok := f.products[id]
    if !ok {
        return catalogclient.Product{}, catalogclient.ErrProductNotFound
    }
    return p, nil
}

// fakePublisher records published events instead of talking to Kafka.
type fakePublisher struct {
    published []message.OrderPlaced
}

func (f *fakePublisher) PublishMessage(ctx context.Context, topic kafka.Topic, key string, payload interface{}) error {
    if e, ok := payload.(message.OrderPlaced); ok {
        f.published = append(f.published, e)
    }
    return nil
}

fakeModules is the whole catalog domain in a dozen lines - possible only because the
order service depends on the slim contracts.Modules interface (stage 10), not the
concrete registry. fakePublisher records what it received, so the test can assert on
a side effect: how many events went out.

The table and the test:

func TestPlaceOrder(t *testing.T) {
    catalog := &fakeModules{products: map[string]catalogclient.Product{
        "p1": {ID: "p1", Name: "Widget", PriceCents: 500},
        "p2": {ID: "p2", Name: "Gadget", PriceCents: 250},
    }}

    tests := []struct {
        name       string
        req        PlaceOrderRequest
        wantTotal  int64
        wantEvents int
        wantErr    error
    }{
        {
            name:       "two items sums line totals and publishes one event",
            req:        PlaceOrderRequest{UserID: "u1", Items: []PlaceOrderItem{{"p1", 2}, {"p2", 1}}},
            wantTotal:  1250,
            wantEvents: 1,
        },
        {
            name:    "no items",
            req:     PlaceOrderRequest{UserID: "u1"},
            wantErr: domain.ErrNoItems,
        },
        {
            name:    "unknown product",
            req:     PlaceOrderRequest{UserID: "u1", Items: []PlaceOrderItem{{"nope", 1}}},
            wantErr: catalogclient.ErrProductNotFound,
        },
        {
            name:    "non-positive quantity",
            req:     PlaceOrderRequest{UserID: "u1", Items: []PlaceOrderItem{{"p1", 0}}},
            wantErr: domain.ErrInvalidQuantity,
        },
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            pub := &fakePublisher{}
            svc := NewService(&fakeRepo{}, catalog, pub)
            got, err := svc.PlaceOrder(context.Background(), tt.req)
            if tt.wantErr != nil {
                if !errors.Is(err, tt.wantErr) {
                    t.Fatalf("want error %v, got %v", tt.wantErr, err)
                }
                return
            }
            if err != nil {
                t.Fatalf("unexpected error: %v", err)
            }
            if got.TotalCents != tt.wantTotal {
                t.Fatalf("want total %d, got %d", tt.wantTotal, got.TotalCents)
            }
            if len(pub.published) != tt.wantEvents {
                t.Fatalf("want %d events published, got %d", tt.wantEvents, len(pub.published))
            }
        })
    }
}

Two assertions earn their place. errors.Is(err, catalogclient.ErrProductNotFound)
still matches even though PlaceOrder wrapped it with %w - stage 06's promise. And
len(pub.published) proves the success path publishes exactly one event and the error
paths publish none, because a fresh fakePublisher is built per row.

Production note: teams can place a //go:generate moq ... line above a port to
generate larger sets of test doubles. The -stub flag makes unconfigured methods
return zero values instead of panicking. Writing one double by hand first keeps the
generated result understandable.

Integration tests

A normal test run must skip this file entirely (no tag, so it is not even compiled):

go test ./...
# ... no catalog/test line runs; the unit suites pass

Now run it for real, against a migrated database:

docker compose up -d
go run . migrate
INTEGRATION_TEST_ENV=true go test -count=1 -tags=integration ./catalog/test/

or:

make test-integration

ok      minimart/catalog/test   0.02s

The product made a full round trip through Postgres. Drop the -tags=integration and
the same command reports no test files - the tag did its job.

Trust it the same way you trusted the unit test in the Unit tests section: temporarily break a column
mapping in the adapter or misspell a query name, watch the integration test fail, then
undo the break.

The unit tests in the Unit tests section prove logic - but they fake the repository, so they can never
catch a wrong column name, a broken query, or a bad row mapping. That is the job of an
integration test: boot the real adapter against a real database and round-trip data
through it.

These two suites must not mix. The convention:

Integration tests live in a <domain>/test/ directory.
Each file opens with //go:build integration, so a plain go test ./... skips them by construction - the unit suite stays fast.
They run only with -tags=integration and an INTEGRATION_TEST_ENV=true runtime guard, so they never fire by accident (in CI, or on a laptop with no database).
They mock only third-party services, never their own database - the SQL is exactly the wiring the test exists to prove.

The two kinds divide cleanly precisely because of the architecture: fast unit tests for
logic (many, run on every save), slower integration tests for wiring (few, run before
merge).

A good integration test has four properties:

Fast enough to run locally. Docker is acceptable; a shared cloud database is not.
Focused. It tests the adapter contract, not every domain corner case.
Deterministic. It owns its test data and does not depend on global row counts.
Real where it matters. If the purpose is SQL wiring, use real Postgres and real migrations.

Create catalog/test/catalog_integration_test.go:

//go:build integration

// Package test holds the catalog domain's integration tests. Unlike the unit tests,
// these run against a REAL Postgres (the docker-compose db) and prove the SQL wiring
// the unit tests deliberately fake out.
//
// They are excluded from a normal `go test ./...` by the build tag above, and guarded
// again at runtime by INTEGRATION_TEST_ENV, so they never run by accident. Run them
// against a migrated database with:
//
//  docker compose up -d
//  go run . migrate
//  INTEGRATION_TEST_ENV=true go test -count=1 -tags=integration ./catalog/test/
package test

import (
    "context"
    "os"
    "testing"

    "github.com/jackc/pgx/v5/pgxpool"

    "minimart/catalog/domain"
    "minimart/catalog/infrastructure/postgres"
    "minimart/conf"
)

// TestCatalogRepository_SaveGetByID round-trips a product through the real Postgres
// adapter: Save, then GetByID, and asserts the value comes back unchanged. The
// upsert query makes the fixed ID safe to re-run.
func TestCatalogRepository_SaveGetByID(t *testing.T) {
    if os.Getenv("INTEGRATION_TEST_ENV") != "true" {
        t.Skip("integration test: set INTEGRATION_TEST_ENV=true (and run against a migrated Postgres)")
    }
    ctx := context.Background()

    pool, err := pgxpool.New(ctx, conf.DatabaseURL())
    if err != nil {
        t.Fatalf("connect: %v", err)
    }
    defer pool.Close()

    // Locally both pools point at the same database.
    repo := postgres.NewCatalogRepository(pool, pool)

    want, err := domain.NewProduct("it-widget", "Integration Widget", 1299, 7)
    if err != nil {
        t.Fatalf("NewProduct: %v", err)
    }
    if err := repo.Save(ctx, want); err != nil {
        t.Fatalf("Save: %v", err)
    }

    got, err := repo.GetByID(ctx, "it-widget")
    if err != nil {
        t.Fatalf("GetByID: %v", err)
    }
    if got != want {
        t.Fatalf("round-trip mismatch: got %+v, want %+v", got, want)
    }
}

Two guards, deliberately redundant: the build tag keeps this file out of the normal
compile, and the INTEGRATION_TEST_ENV check skips it at runtime if it does get
compiled. It constructs the real CatalogRepository (both pools pointing at the one
local database), saves a product, and reads it back - exercising the sqlc query, the row
mapping, and the schema together. got != want works because domain.Product is a
comparable value.

The fixed ID is deliberate because the write is an upsert. In tests that insert
append-only rows, prefer unique IDs per test or per table, and assert the row you own
instead of "there are N rows now." Shared databases become flaky when tests depend on
global counts.

Add one convenience target to the Makefile from the **Run the stack section:**

.PHONY: test-integration

test-integration:
    INTEGRATION_TEST_ENV=true go test -count=1 -tags=integration ./catalog/test/

-count=1 disables Go's test cache. Infrastructure tests can pass from cache even
after a compose file, migration, or environment variable changed, so make the command
run the database round trip every time.

Production note: a team can keep this kind of suite in <domain>/test/ and run
it in CI against Postgres after migrations. These tests catch renamed columns and
missing migrations, which unit tests structurally cannot see.

Where to go

The architecture, recapped

MiniMart is two request-serving domains (catalog, order) and one worker-only domain
(notification), each a hexagon with four layers, wired by one module lifecycle.

The Dependency Rule. Imports point inward. domain imports nothing; application imports domain; presentation imports application; infrastructure imports the domain ports and entities it implements. Every import statement obeys it.
Valid by construction. domain.NewProduct / NewOrder are the only ways to make an entity, so every value in the system is already valid.
Ports in the domain, adapters in infrastructure. domain.Repository is an interface the domain owns; memory and postgres implement it. The var _ domain.Repository line makes the fit a compile error if it drifts.
Inject interfaces, never construct. Services take ports as constructor arguments; the module's Init is the one place concrete adapters are named - which is why the storage swap (stage 11) touched no business code.
Boot in phases, verify before serving. Init → RegisterContracts → Verify → RegisterHTTP (server) or RegisterWorkers (worker). A missing contract is a crash at startup, not a nil panic on the first request.
Cross domains only through published contracts. The order domain calls the catalog through catalog/presentation/module/client and the contracts.Modules interface - never its application or domain.

Two transports (HTTP, Kafka) are both just input adapters in presentation/. Two test
kinds (unit for logic, integration for wiring) divide cleanly because the ports made
them. Storage, broker, and delivery are all replaceable behind their ports.

The use cases also split naturally into commands and queries: PlaceOrder changes
state and emits an event; GetOrder asks a question. MiniMart keeps them as methods
on one service for readability. Larger systems often make that split explicit with
command/ and query/ packages or read models, but the rule is the same: writes
protect invariants, reads serve callers.

Where to go next

Read a larger service with this shape. Look for sealed domains, HTTP and message adapters side by side, generated mocks, and integration suites gated by build tags. You will recognize every piece.
Add a domain. A user hexagon: publish a contract, have order record which user placed an order. No checklist this time - you know the shape.
Add a use case with a new rule. Reject an order when quantity > stock. Decide which domain owns that rule before writing it - the catalog's stock is stale by checkout time, so the answer is not obvious.
Add observability. Structured logs with a request ID threaded through ctx; metrics on the HTTP edge and the consumer loop; traces across the publish/consume boundary. All of it attaches at the edges - the core stays clean.
Add a component test. Start the HTTP adapter with httptest, use real Postgres, fake the catalog contract or publisher, and test one happy path through a single service. Keep edge cases in unit tests.
Harden delivery. Replace the best-effort publish (the Publish on place section) with a transactional outbox, so an OrderPlaced event can never be lost.
Add authorization. Use an identity provider for authentication at the edge, but pass a typed actor into use cases for authorization decisions. Do not hide required identity in context.Context.

The value you carry off is not MiniMart. It is that the next codebase shaped like this -
and many are - is already legible to you: you know where each rule lives and why every
file is where it is.

DEV Community: huzaifa nur

MiniCart: Hexagonal Architecture in Go

What you'll build

The rule

Toolbox & working copy

Verify

Why hexagonal

The Dependency Rule

Where main.go fits

The health server

What you learned

The Domain

Entities

Valid by construction

Verify

Money in cents

Table-driven tests

Verify

Ports & Adapters

The port

Verify

The in-memory adapter

Test the adapter

Verify

What you learned

Use Cases

The service

Verify

One use case per file

Verify

Reads

Verify

Test the use case

Verify

What you learned

The Front Door

Input adapters & DTOs

Verify

Handlers

Verify

Wire it

What you learned

Honest Errors

Translate at the edge

Map domain errors

What you learned

The Module Pattern

Why modules

The Module interface

Verify

A self-wiring domain

Verify

The boot loop

What you learned

A Second Domain

The order entity

Verify

Port and adapter

Verify

Place order

Verify

Order HTTP

Verify

Wire and observe

What you learned

Publish a Contract

The forbidden import

The client package

Verify

The adapter

Verify

The registry

Verify

Four-phase boot

What you learned

The Handshake

Consume a contract

Verify

Real prices

Verify

Where `main.go` fits