Why DDD: applications && infrastructure

The problemThe use case, the storage and the incoming call spread across layers, and what each of them knows about the domain gets discovered in production: where the transaction started, who sent the fact, and why a subscriber learned about something that is not in the database.

The domain is described and knows nothing about the outside: it has an aggregate, values, facts and two ports.

What follows is everything around it: the use cases, the port implementations, the incoming call and the wiring of the application.

Step 1 of 10

Use case: issue an invoice

The issuing module finally has code. The use case takes three steps: build the aggregate, save it, publish the facts.

Not a single domain rule is here — they stayed in Issue. Here there is only order, and that is what application is: it hands out work and keeps the operation on course.

The use case takes what the domain needs as plain parameters. Whatever arrives over HTTP or from the bus does not reach this far: those are transport DTOs, and the transport translates them.

The dependencies are two ports and no implementations. That is why the use case has one reason to change — the order of the operation: swap the database or the bus, and it stays as it is.

Publishing comes after saving, not before: a subscriber should not learn about something that never reached storage. There is still no atomicity between those two steps — that is what a transactional outbox is for, and it is a separate conversation.

Step 2 of 10

Use case: take a payment

The second module, the same order, a different story: load the aggregate, call the method, save, publish.

The "already paid" check is not written here — it is in MarkPaid. The use case only passes the error up: were it checking on its own, the rule would live in two places, and one day one of them would fall behind.

It also shows why the repository hands out the whole aggregate: state is changed by its methods, and for that you need the aggregate itself, not a row from the database.

Step 3 of 10

The ports are there, the implementation is not

On the right is the storage port from the second chapter. The domain declared what it needs: take an invoice by number and save it whole. Who does that is not its business.

Time to do it. And the first question of the implementation is not about SQL: how do you return an aggregate whose fields are all private? Issue will not do — it creates a new invoice and records the fact "invoice issued", while we are loading one that already exists.

Step 4 of 10

How the aggregate comes back from storage

Load is the second way to come into being: not "create" but "bring back what was already there". It records no facts and checks no invariants: the data was already in storage, and checking it again means not trusting your own write.

It lives in the domain, because only the domain can rebuild its own aggregate. Handing that job to the infrastructure means opening the fields to it — and with them the ability to assemble an invoice the domain does not allow.

Step 5 of 10

The port implementation

Infrastructure: database/sql, two tables, queries. The domain knows nothing about this file — knowledge goes from the outside in.

Save writes the invoice and its lines with two queries. That already needs a transaction: anything can fail in between, and storage would keep an invoice with no lines — a state the domain does not allow.

The connection comes from a conn(ctx, db) function rather than a field. Why is the subject of the next steps.

Step 6 of 10

Saved and published

Back to the use case. It makes two calls: save and publish. Separately both are right; together they are not.

If Publish fails, the invoice is in storage and nobody knows about it: delivery does not start packing, accounting sees no charge. Swapping the calls is worse: Save fails after a successful Publish, and subscribers know about an invoice that does not exist.

I left a note about this back in the first step. Time to close it: there must be one operation, not two.

Step 7 of 10

Unit of work

A unit of work is a port that says one thing: do the work whole or do not do it at all. There is no Begin, no Commit and not even the word "transaction" in the domain — there is a function someone will run on their own responsibility.

That is why the port stands next to the others: the domain does not know there is a Postgres transaction behind it and would work over the same interface on anything else. The only thing it demands is that "whole" really means whole.

Step 8 of 10

One operation instead of two

The use case changed in one place: the save and the publish moved inside Do. The order of the steps is the same; the boundary changed — it is one operation now. Payment and overdue moved into Do the same way: the tree marks them.

The implementation puts the transaction into ctx, and the adapters take it from there with that same conn function. So the use case passes no transaction around and never sees one: what it needs is a boundary, not a connection.

It is easy to overdo this. A unit of work is not "a transaction per query" and not a way to change two aggregates at once: the aggregate is still the consistency boundary, while Do holds the boundary of the operation.

Step 9 of 10

A bus does not join a transaction

One lie is left. A bus is not a database: it cannot be rolled back with the transaction. Send a fact inside Do, and a failure at commit leaves subscribers with a fact about an invoice that does not exist.

So the publishing implementation sends nothing. It writes the fact as a row in the same transaction, next to the invoice: either both are there or neither is.

A separate process sends them — it reads the table, puts the facts on the bus and marks what it sent. It may send twice, so a subscriber has to be idempotent — but it cannot send what never happened.

billing/GLOSSARY.md

Glossary

One meaning per word inside this context. The code, the events, the API and the person on the call all spell it the same way.

“Payment” in three departments

Department	What it calls a payment	What it is called here
Product	The purchase went through, the customer saw the checkmark	An order event. Not here
Processing	The money is held, nothing was captured	Authorization
Finance	The money showed up in a statement two days later	Settlement

Words

Authorization. The issuer agreed to hold the amount. No money moved, and the hold expires on its own.

Capture. The instruction to take what was held. From here on the money has left the payer’s account.

Settlement. The money reached our account, and the provider’s statement says so. It arrives days later, and it may not arrive at all.

Payment. One attempt to collect money for one order, with a lifecycle of its own: authorized, captured, refunded. The word means this and nothing else.

Words that are not here

Purchase. A product event: the customer saw the checkmark. It lives with orders, and there is nothing for it to mean here.

billing/invoice/domains/invoice/invoice.go

package invoice

import (
	"time"

	"billing/invoice/domains/invoice/events"
	"billing/invoice/domains/invoice/vo"
)

// the invoice: aggregate root
type Invoice struct {
	number   Number
	customer CustomerID
	lines    []Line
	total    vo.Money
	dueOn    time.Time
	status   Status
	facts    []events.Event
}

// builds an invoice and sums up the lines
func Issue(
	number Number,
	customer CustomerID,
	lines []Line,
	dueOn time.Time,
) (*Invoice, error) {
	if len(lines) == 0 {
		return nil, ErrNoLines
	}

	total := vo.NewMoney(0)
	for _, line := range lines {
		total = total.Add(line.Amount())
	}

	invoice := &Invoice{
		number:   number,
		customer: customer,
		// a copy of the lines: unchangeable from outside
		lines:    append([]Line(nil), lines...),
		total:    total,
		dueOn:    dueOn,
		status:   StatusIssued,
	}

	// records the fact; sending it is not for the aggregate to do
	invoice.facts = append(invoice.facts, events.Issued{
		Number:   string(number),
		Customer: string(customer),
		Total:    total,
	})

	return invoice, nil
}

// hands the recorded facts to the outside
func (i *Invoice) Events() []events.Event { return i.facts }

func (i *Invoice) Total() vo.Money  { return i.total }
func (i *Invoice) DueOn() time.Time { return i.dueOn }
func (i *Invoice) Status() Status   { return i.status }

billing/invoice/domains/invoice/paid.go

package invoice

import "billing/invoice/domains/invoice/events"

// marks the invoice paid; paying it twice is not allowed
func (i *Invoice) MarkPaid() error {
	if i.status == StatusPaid {
		return ErrAlreadyPaid
	}

	i.status = StatusPaid

	// records the fact; sending it is not for the aggregate to do
	i.facts = append(i.facts, events.Paid{Number: string(i.number)})

	return nil
}

billing/invoice/domains/invoice/charged.go

package invoice

import (
	"billing/invoice/domains/invoice/events"
	"billing/invoice/domains/invoice/vo"
)

// puts the fee on the invoice; a paid invoice takes none
func (i *Invoice) ChargePenalty(amount vo.Money) error {
	if i.status == StatusPaid {
		return ErrAlreadyPaid
	}

	if amount.Equal(vo.NewMoney(0)) {
		return nil
	}

	i.lines = append(i.lines, Line{Quantity: 1, Price: amount})
	i.total = i.total.Add(amount)

	// records the fact; sending it is not for the aggregate to do
	i.facts = append(i.facts, events.PenaltyCharged{
		Number: string(i.number),
		Amount: amount,
	})

	return nil
}

billing/invoice/domains/invoice/events/event.go

package events

import "billing/invoice/domains/invoice/vo"

// a domain fact; the name goes to the bus as the message type
type Event interface {
	FactName() string
}

// the invoice has been issued
type Issued struct {
	Number   string
	Customer string
	Total    vo.Money
}

func (Issued) FactName() string { return "invoice.issued" }

// the invoice has been paid
type Paid struct {
	Number string
}

func (Paid) FactName() string { return "invoice.paid" }

// the invoice was charged a late fee
type PenaltyCharged struct {
	Number string
	Amount vo.Money
}

func (PenaltyCharged) FactName() string { return "invoice.penalty_charged" }

billing/invoice/domains/invoice/calendar.go

package invoice

import "time"

// the working calendar: part of the model, not a storage port
type Calendar interface {
	Workdays(from time.Time, to time.Time) int
}

billing/invoice/domains/invoice/services/penalty/penalty.go

package penalty

import (
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// the rule: an invoice, a rate and a calendar — an amount out
func Amount(
	overdue *invoice.Invoice,
	now time.Time,
	perWorkday vo.Money,
	calendar invoice.Calendar,
) vo.Money {
	// the rule takes the due date from the invoice itself, not from the caller
	late := calendar.Workdays(overdue.DueOn(), now)
	if late <= 0 {
		return vo.NewMoney(0)
	}

	return vo.NewMoney(perWorkday.Get() * int64(late))
}

billing/invoice/domains/invoice/repository.go

package invoice

import "context"

// the port: how an invoice reaches storage and comes back
type Repository interface {
	ByNumber(ctx context.Context, number Number) (*Invoice, error)
	Save(ctx context.Context, invoice *Invoice) error
}

billing/invoice/domains/invoice/publisher.go

package invoice

import (
	"context"

	"billing/invoice/domains/invoice/events"
)

// the port: where facts are sent
type Publisher interface {
	Publish(ctx context.Context, facts ...events.Event) error
}

billing/invoice/domains/invoice/vo/money.go

package vo

// an amount in cents
type Money struct {
	minor int64
}

func NewMoney(minor int64) Money {
	return Money{minor: minor}
}

func (m Money) Add(other Money) Money {
	return Money{minor: m.minor + other.minor}
}

func (m Money) Equal(other Money) bool {
	return m.minor == other.minor
}

func (m Money) Get() int64 {
	return m.minor
}

billing/invoice/domains/invoice/rules/overdue.go

package rules

import (
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// the specification contract: one question about one aggregate
type Specification interface {
	IsSatisfiedBy(inv *invoice.Invoice) bool
}

// the predicate: is this invoice overdue?
type Overdue struct {
	now      time.Time
	calendar invoice.Calendar
}

func NewOverdue(now time.Time, calendar invoice.Calendar) Overdue {
	return Overdue{now: now, calendar: calendar}
}

// a paid invoice is never overdue
func (o Overdue) IsSatisfiedBy(inv *invoice.Invoice) bool {
	if inv.Status() == invoice.StatusPaid {
		return false
	}

	return o.calendar.Workdays(inv.DueOn(), o.now) > 0
}

// a second predicate: the invoice is above the limit
type OverBudget struct {
	limit vo.Money
}

func NewOverBudget(limit vo.Money) OverBudget {
	return OverBudget{limit: limit}
}

func (b OverBudget) IsSatisfiedBy(inv *invoice.Invoice) bool {
	return inv.Total().Get() > b.limit.Get()
}

// composition: requires every predicate at once
type All struct {
	specs []Specification
}

func AllOf(specs ...Specification) All {
	return All{specs: specs}
}

func (a All) IsSatisfiedBy(inv *invoice.Invoice) bool {
	for _, spec := range a.specs {
		if !spec.IsSatisfiedBy(inv) {
			return false
		}
	}

	return true
}

billing/invoice/applications/overdue/charge.go

package overdue

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/rules"
	"billing/invoice/domains/invoice/services/penalty"
	"billing/invoice/domains/invoice/vo"
)

// two ports, a calendar and a rate — all the use case needs
type UseCase struct {
	invoices   invoice.Repository
	publisher  invoice.Publisher
	calendar   invoice.Calendar
	perWorkday vo.Money
}

func New(
	invoices invoice.Repository,
	publisher invoice.Publisher,
	calendar invoice.Calendar,
	perWorkday vo.Money,
) *UseCase {
	return &UseCase{
		invoices:   invoices,
		publisher:  publisher,
		calendar:   calendar,
		perWorkday: perWorkday,
	}
}

// load, calculate, apply, save, tell
func (u *UseCase) Run(ctx context.Context, number invoice.Number, now time.Time) error {
	overdue, err := u.invoices.ByNumber(ctx, number)
	if err != nil {
		return err
	}

	// the use case asks the rule instead of trusting the caller
	if !rules.NewOverdue(now, u.calendar).IsSatisfiedBy(overdue) {
		return nil
	}

	// the rule computes the amount from the invoice, the rate and the calendar
	amount := penalty.Amount(overdue, now, u.perWorkday, u.calendar)

	// only the invoice itself can charge the fee to the invoice
	if err := overdue.ChargePenalty(amount); err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, overdue); err != nil {
		return err
	}

	return u.publisher.Publish(ctx, overdue.Events()...)
}

billing/invoice/applications/overdue/charge.go

package overdue

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/rules"
	"billing/invoice/domains/invoice/services/penalty"
	"billing/invoice/domains/invoice/vo"
)

// two ports, a calendar and a rate — all the use case needs
type UseCase struct {
	uow        invoice.UnitOfWork
	invoices   invoice.Repository
	publisher  invoice.Publisher
	calendar   invoice.Calendar
	perWorkday vo.Money
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
	calendar invoice.Calendar,
	perWorkday vo.Money,
) *UseCase {
	return &UseCase{
		uow:        uow,
		invoices:   invoices,
		publisher:  publisher,
		calendar:   calendar,
		perWorkday: perWorkday,
	}
}

// load, calculate, apply, save, tell
func (u *UseCase) Run(ctx context.Context, number invoice.Number, now time.Time) error {
	return u.uow.Do(ctx, func(ctx context.Context) error {
		overdue, err := u.invoices.ByNumber(ctx, number)
		if err != nil {
			return err
		}

		// the use case asks the rule instead of trusting the caller
		if !rules.NewOverdue(now, u.calendar).IsSatisfiedBy(overdue) {
			return nil
		}

		// the rule computes the amount from the invoice, the rate and the calendar
		amount := penalty.Amount(overdue, now, u.perWorkday, u.calendar)

		// only the invoice itself can charge the fee to the invoice
		if err := overdue.ChargePenalty(amount); err != nil {
			return err
		}

		if err := u.invoices.Save(ctx, overdue); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, overdue.Events()...)
	})
}

billing/invoice/applications/issuing/issue.go

package issuing

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
)

// dependencies are domain ports and nothing else
type UseCase struct {
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(invoices invoice.Repository, publisher invoice.Publisher) *UseCase {
	return &UseCase{invoices: invoices, publisher: publisher}
}

// the order of the operation: build, save, tell
func (u *UseCase) Run(
	ctx context.Context,
	number invoice.Number,
	customer invoice.CustomerID,
	lines []invoice.Line,
	dueOn time.Time,
) error {
	issued, err := invoice.Issue(number, customer, lines, dueOn)
	if err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, issued); err != nil {
		return err
	}

	// facts leave after the save, not before
	return u.publisher.Publish(ctx, issued.Events()...)
}

billing/invoice/applications/issuing/issue.go

package issuing

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
)

// one more port next to the others: the unit of work
type UseCase struct {
	uow       invoice.UnitOfWork
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
) *UseCase {
	return &UseCase{uow: uow, invoices: invoices, publisher: publisher}
}

// the same order, a different boundary
func (u *UseCase) Run(
	ctx context.Context,
	number invoice.Number,
	customer invoice.CustomerID,
	lines []invoice.Line,
	dueOn time.Time,
) error {
	issued, err := invoice.Issue(number, customer, lines, dueOn)
	if err != nil {
		return err
	}

	// the save and the facts happen inside one operation
	return u.uow.Do(ctx, func(ctx context.Context) error {
		if err := u.invoices.Save(ctx, issued); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, issued.Events()...)
	})
}

billing/invoice/applications/payment/pay.go

package payment

import (
	"context"

	"billing/invoice/domains/invoice"
)

// dependencies are domain ports and nothing else
type UseCase struct {
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(invoices invoice.Repository, publisher invoice.Publisher) *UseCase {
	return &UseCase{invoices: invoices, publisher: publisher}
}

// load, call the method, save, tell
func (u *UseCase) Run(ctx context.Context, number invoice.Number) error {
	paid, err := u.invoices.ByNumber(ctx, number)
	if err != nil {
		return err
	}

	if err := paid.MarkPaid(); err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, paid); err != nil {
		return err
	}

	// facts leave after the save, not before
	return u.publisher.Publish(ctx, paid.Events()...)
}

billing/invoice/applications/payment/pay.go

package payment

import (
	"context"

	"billing/invoice/domains/invoice"
)

// one more port next to the others: the unit of work
type UseCase struct {
	uow       invoice.UnitOfWork
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
) *UseCase {
	return &UseCase{uow: uow, invoices: invoices, publisher: publisher}
}

// load, call the method, save, tell
func (u *UseCase) Run(ctx context.Context, number invoice.Number) error {
	return u.uow.Do(ctx, func(ctx context.Context) error {
		paid, err := u.invoices.ByNumber(ctx, number)
		if err != nil {
			return err
		}

		if err := paid.MarkPaid(); err != nil {
			return err
		}

		if err := u.invoices.Save(ctx, paid); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, paid.Events()...)
	})
}

billing/invoice/domains/invoice/load.go

package invoice

import (
	"time"

	"billing/invoice/domains/invoice/vo"
)

// rebuilds the invoice from what is in storage; no facts recorded
func Load(
	number Number,
	customer CustomerID,
	lines []Line,
	total vo.Money,
	dueOn time.Time,
	status Status,
) *Invoice {
	return &Invoice{
		number:   number,
		customer: customer,
		lines:    lines,
		total:    total,
		dueOn:    dueOn,
		status:   status,
	}
}

billing/invoice/domains/invoice/uow.go

package invoice

import "context"

// the port: do the work whole or do not do it at all
type UnitOfWork interface {
	Do(ctx context.Context, work func(ctx context.Context) error) error
}

billing/invoice/infrastructure/postgres/invoices.go

package postgres

import (
	"context"
	"database/sql"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// the storage port implementation
type Invoices struct {
	db *sql.DB
}

func NewInvoices(db *sql.DB) *Invoices {
	return &Invoices{db: db}
}

// loads the invoice: the lines come with a separate query
func (r *Invoices) ByNumber(ctx context.Context, number invoice.Number) (*invoice.Invoice, error) {
	var (
		customer string
		minor    int64
		dueOn    time.Time
		status   string
	)

	err := conn(ctx, r.db).
		QueryRowContext(ctx, selectInvoice, string(number)).
		Scan(&customer, &minor, &dueOn, &status)
	if err != nil {
		return nil, err
	}

	lines, err := r.lines(ctx, number)
	if err != nil {
		return nil, err
	}

	// rebuilds the aggregate instead of creating a new one
	return invoice.Load(
		number,
		invoice.CustomerID(customer),
		lines,
		vo.NewMoney(minor),
		dueOn,
		invoice.Status(status),
	), nil
}

// saves the invoice and its lines: two queries, one transaction
func (r *Invoices) Save(ctx context.Context, saved *invoice.Invoice) error {
	db := conn(ctx, r.db)

	if _, err := db.ExecContext(ctx, upsertInvoice, saved); err != nil {
		return err
	}

	_, err := db.ExecContext(ctx, replaceLines, saved)

	return err
}

billing/invoice/infrastructure/postgres/uow.go

package postgres

import (
	"context"
	"database/sql"
)

type txKey struct{}

// a transaction hidden behind a port
type UnitOfWork struct {
	db *sql.DB
}

func NewUnitOfWork(db *sql.DB) *UnitOfWork {
	return &UnitOfWork{db: db}
}

// open, hand over the work, close: one commit per operation
func (u *UnitOfWork) Do(ctx context.Context, work func(ctx context.Context) error) error {
	tx, err := u.db.BeginTx(ctx, nil)
	if err != nil {
		return err
	}

	if err := work(context.WithValue(ctx, txKey{}, tx)); err != nil {
		// an error inside means a full rollback
		_ = tx.Rollback()

		return err
	}

	return tx.Commit()
}

// adapters take the connection here: the transaction sits in ctx
func conn(ctx context.Context, db *sql.DB) interface {
	ExecContext(context.Context, string, ...any) (sql.Result, error)
	QueryRowContext(context.Context, string, ...any) *sql.Row
} {
	if tx, ok := ctx.Value(txKey{}).(*sql.Tx); ok {
		return tx
	}

	return db
}

billing/invoice/infrastructure/postgres/outbox.go

package postgres

import (
	"context"
	"database/sql"
	"encoding/json"

	"billing/invoice/domains/invoice/events"
)

// the publishing port implementation
type Outbox struct {
	db *sql.DB
}

func NewOutbox(db *sql.DB) *Outbox {
	return &Outbox{db: db}
}

// facts do not leave for the bus; they land next to the invoice
func (o *Outbox) Publish(ctx context.Context, facts ...events.Event) error {
	db := conn(ctx, o.db)

	for _, event := range facts {
		body, err := json.Marshal(event)
		if err != nil {
			return err
		}

		// the same transaction as the invoice
		if _, err := db.ExecContext(ctx, insertOutbox, event.FactName(), body); err != nil {
			return err
		}
	}

	return nil
}

Step 10 of 10

What we ended up with around the domain

The tree shows the whole layout: the domain in domains/invoice, the use cases in applications, one module per slice. Click a file to read it.

applications/issuing/issue.go — issue an invoice, all inside one unit of work.
applications/payment/pay.go — take a payment.
domains/invoice/load.go — how the aggregate comes back from storage.
domains/invoice/uow.go — the unit of work port.
infrastructure/postgres/invoices.go — the storage implementation.
infrastructure/postgres/uow.go — the transaction and conn(ctx, db).
infrastructure/postgres/outbox.go — facts as a row in the same transaction.

Over the whole chapter the domain grew by two files: load.go, which is about rebuilding its own aggregate, and uow.go, one more port. Everything else landed outside, behind the ports the domain declared itself.

What is still missing: the incoming call and the wiring of the application. Those come next.

billing/GLOSSARY.md

Glossary

One meaning per word inside this context. The code, the events, the API and the person on the call all spell it the same way.

“Payment” in three departments

Department	What it calls a payment	What it is called here
Product	The purchase went through, the customer saw the checkmark	An order event. Not here
Processing	The money is held, nothing was captured	Authorization
Finance	The money showed up in a statement two days later	Settlement

Words

Authorization. The issuer agreed to hold the amount. No money moved, and the hold expires on its own.

Capture. The instruction to take what was held. From here on the money has left the payer’s account.

Settlement. The money reached our account, and the provider’s statement says so. It arrives days later, and it may not arrive at all.

Payment. One attempt to collect money for one order, with a lifecycle of its own: authorized, captured, refunded. The word means this and nothing else.

Words that are not here

Purchase. A product event: the customer saw the checkmark. It lives with orders, and there is nothing for it to mean here.

billing/invoice/domains/invoice/invoice.go

package invoice

import (
	"time"

	"billing/invoice/domains/invoice/events"
	"billing/invoice/domains/invoice/vo"
)

// the invoice: aggregate root
type Invoice struct {
	number   Number
	customer CustomerID
	lines    []Line
	total    vo.Money
	dueOn    time.Time
	status   Status
	facts    []events.Event
}

// builds an invoice and sums up the lines
func Issue(
	number Number,
	customer CustomerID,
	lines []Line,
	dueOn time.Time,
) (*Invoice, error) {
	if len(lines) == 0 {
		return nil, ErrNoLines
	}

	total := vo.NewMoney(0)
	for _, line := range lines {
		total = total.Add(line.Amount())
	}

	invoice := &Invoice{
		number:   number,
		customer: customer,
		// a copy of the lines: unchangeable from outside
		lines:    append([]Line(nil), lines...),
		total:    total,
		dueOn:    dueOn,
		status:   StatusIssued,
	}

	// records the fact; sending it is not for the aggregate to do
	invoice.facts = append(invoice.facts, events.Issued{
		Number:   string(number),
		Customer: string(customer),
		Total:    total,
	})

	return invoice, nil
}

// hands the recorded facts to the outside
func (i *Invoice) Events() []events.Event { return i.facts }

func (i *Invoice) Total() vo.Money  { return i.total }
func (i *Invoice) DueOn() time.Time { return i.dueOn }
func (i *Invoice) Status() Status   { return i.status }

billing/invoice/domains/invoice/paid.go

package invoice

import "billing/invoice/domains/invoice/events"

// marks the invoice paid; paying it twice is not allowed
func (i *Invoice) MarkPaid() error {
	if i.status == StatusPaid {
		return ErrAlreadyPaid
	}

	i.status = StatusPaid

	// records the fact; sending it is not for the aggregate to do
	i.facts = append(i.facts, events.Paid{Number: string(i.number)})

	return nil
}

billing/invoice/domains/invoice/charged.go

package invoice

import (
	"billing/invoice/domains/invoice/events"
	"billing/invoice/domains/invoice/vo"
)

// puts the fee on the invoice; a paid invoice takes none
func (i *Invoice) ChargePenalty(amount vo.Money) error {
	if i.status == StatusPaid {
		return ErrAlreadyPaid
	}

	if amount.Equal(vo.NewMoney(0)) {
		return nil
	}

	i.lines = append(i.lines, Line{Quantity: 1, Price: amount})
	i.total = i.total.Add(amount)

	// records the fact; sending it is not for the aggregate to do
	i.facts = append(i.facts, events.PenaltyCharged{
		Number: string(i.number),
		Amount: amount,
	})

	return nil
}

billing/invoice/domains/invoice/events/event.go

package events

import "billing/invoice/domains/invoice/vo"

// a domain fact; the name goes to the bus as the message type
type Event interface {
	FactName() string
}

// the invoice has been issued
type Issued struct {
	Number   string
	Customer string
	Total    vo.Money
}

func (Issued) FactName() string { return "invoice.issued" }

// the invoice has been paid
type Paid struct {
	Number string
}

func (Paid) FactName() string { return "invoice.paid" }

// the invoice was charged a late fee
type PenaltyCharged struct {
	Number string
	Amount vo.Money
}

func (PenaltyCharged) FactName() string { return "invoice.penalty_charged" }

billing/invoice/domains/invoice/calendar.go

package invoice

import "time"

// the working calendar: part of the model, not a storage port
type Calendar interface {
	Workdays(from time.Time, to time.Time) int
}

billing/invoice/domains/invoice/services/penalty/penalty.go

package penalty

import (
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// the rule: an invoice, a rate and a calendar — an amount out
func Amount(
	overdue *invoice.Invoice,
	now time.Time,
	perWorkday vo.Money,
	calendar invoice.Calendar,
) vo.Money {
	// the rule takes the due date from the invoice itself, not from the caller
	late := calendar.Workdays(overdue.DueOn(), now)
	if late <= 0 {
		return vo.NewMoney(0)
	}

	return vo.NewMoney(perWorkday.Get() * int64(late))
}

billing/invoice/domains/invoice/repository.go

package invoice

import "context"

// the port: how an invoice reaches storage and comes back
type Repository interface {
	ByNumber(ctx context.Context, number Number) (*Invoice, error)
	Save(ctx context.Context, invoice *Invoice) error
}

billing/invoice/domains/invoice/publisher.go

package invoice

import (
	"context"

	"billing/invoice/domains/invoice/events"
)

// the port: where facts are sent
type Publisher interface {
	Publish(ctx context.Context, facts ...events.Event) error
}

billing/invoice/domains/invoice/vo/money.go

package vo

// an amount in cents
type Money struct {
	minor int64
}

func NewMoney(minor int64) Money {
	return Money{minor: minor}
}

func (m Money) Add(other Money) Money {
	return Money{minor: m.minor + other.minor}
}

func (m Money) Equal(other Money) bool {
	return m.minor == other.minor
}

func (m Money) Get() int64 {
	return m.minor
}

billing/invoice/domains/invoice/rules/overdue.go

package rules

import (
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// the specification contract: one question about one aggregate
type Specification interface {
	IsSatisfiedBy(inv *invoice.Invoice) bool
}

// the predicate: is this invoice overdue?
type Overdue struct {
	now      time.Time
	calendar invoice.Calendar
}

func NewOverdue(now time.Time, calendar invoice.Calendar) Overdue {
	return Overdue{now: now, calendar: calendar}
}

// a paid invoice is never overdue
func (o Overdue) IsSatisfiedBy(inv *invoice.Invoice) bool {
	if inv.Status() == invoice.StatusPaid {
		return false
	}

	return o.calendar.Workdays(inv.DueOn(), o.now) > 0
}

// a second predicate: the invoice is above the limit
type OverBudget struct {
	limit vo.Money
}

func NewOverBudget(limit vo.Money) OverBudget {
	return OverBudget{limit: limit}
}

func (b OverBudget) IsSatisfiedBy(inv *invoice.Invoice) bool {
	return inv.Total().Get() > b.limit.Get()
}

// composition: requires every predicate at once
type All struct {
	specs []Specification
}

func AllOf(specs ...Specification) All {
	return All{specs: specs}
}

func (a All) IsSatisfiedBy(inv *invoice.Invoice) bool {
	for _, spec := range a.specs {
		if !spec.IsSatisfiedBy(inv) {
			return false
		}
	}

	return true
}

billing/invoice/applications/overdue/charge.go

package overdue

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/rules"
	"billing/invoice/domains/invoice/services/penalty"
	"billing/invoice/domains/invoice/vo"
)

// two ports, a calendar and a rate — all the use case needs
type UseCase struct {
	invoices   invoice.Repository
	publisher  invoice.Publisher
	calendar   invoice.Calendar
	perWorkday vo.Money
}

func New(
	invoices invoice.Repository,
	publisher invoice.Publisher,
	calendar invoice.Calendar,
	perWorkday vo.Money,
) *UseCase {
	return &UseCase{
		invoices:   invoices,
		publisher:  publisher,
		calendar:   calendar,
		perWorkday: perWorkday,
	}
}

// load, calculate, apply, save, tell
func (u *UseCase) Run(ctx context.Context, number invoice.Number, now time.Time) error {
	overdue, err := u.invoices.ByNumber(ctx, number)
	if err != nil {
		return err
	}

	// the use case asks the rule instead of trusting the caller
	if !rules.NewOverdue(now, u.calendar).IsSatisfiedBy(overdue) {
		return nil
	}

	// the rule computes the amount from the invoice, the rate and the calendar
	amount := penalty.Amount(overdue, now, u.perWorkday, u.calendar)

	// only the invoice itself can charge the fee to the invoice
	if err := overdue.ChargePenalty(amount); err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, overdue); err != nil {
		return err
	}

	return u.publisher.Publish(ctx, overdue.Events()...)
}

billing/invoice/applications/overdue/charge.go

package overdue

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/rules"
	"billing/invoice/domains/invoice/services/penalty"
	"billing/invoice/domains/invoice/vo"
)

// two ports, a calendar and a rate — all the use case needs
type UseCase struct {
	uow        invoice.UnitOfWork
	invoices   invoice.Repository
	publisher  invoice.Publisher
	calendar   invoice.Calendar
	perWorkday vo.Money
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
	calendar invoice.Calendar,
	perWorkday vo.Money,
) *UseCase {
	return &UseCase{
		uow:        uow,
		invoices:   invoices,
		publisher:  publisher,
		calendar:   calendar,
		perWorkday: perWorkday,
	}
}

// load, calculate, apply, save, tell
func (u *UseCase) Run(ctx context.Context, number invoice.Number, now time.Time) error {
	return u.uow.Do(ctx, func(ctx context.Context) error {
		overdue, err := u.invoices.ByNumber(ctx, number)
		if err != nil {
			return err
		}

		// the use case asks the rule instead of trusting the caller
		if !rules.NewOverdue(now, u.calendar).IsSatisfiedBy(overdue) {
			return nil
		}

		// the rule computes the amount from the invoice, the rate and the calendar
		amount := penalty.Amount(overdue, now, u.perWorkday, u.calendar)

		// only the invoice itself can charge the fee to the invoice
		if err := overdue.ChargePenalty(amount); err != nil {
			return err
		}

		if err := u.invoices.Save(ctx, overdue); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, overdue.Events()...)
	})
}

billing/invoice/applications/issuing/issue.go

package issuing

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
)

// dependencies are domain ports and nothing else
type UseCase struct {
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(invoices invoice.Repository, publisher invoice.Publisher) *UseCase {
	return &UseCase{invoices: invoices, publisher: publisher}
}

// the order of the operation: build, save, tell
func (u *UseCase) Run(
	ctx context.Context,
	number invoice.Number,
	customer invoice.CustomerID,
	lines []invoice.Line,
	dueOn time.Time,
) error {
	issued, err := invoice.Issue(number, customer, lines, dueOn)
	if err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, issued); err != nil {
		return err
	}

	// facts leave after the save, not before
	return u.publisher.Publish(ctx, issued.Events()...)
}

billing/invoice/applications/issuing/issue.go

package issuing

import (
	"context"
	"time"

	"billing/invoice/domains/invoice"
)

// one more port next to the others: the unit of work
type UseCase struct {
	uow       invoice.UnitOfWork
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
) *UseCase {
	return &UseCase{uow: uow, invoices: invoices, publisher: publisher}
}

// the same order, a different boundary
func (u *UseCase) Run(
	ctx context.Context,
	number invoice.Number,
	customer invoice.CustomerID,
	lines []invoice.Line,
	dueOn time.Time,
) error {
	issued, err := invoice.Issue(number, customer, lines, dueOn)
	if err != nil {
		return err
	}

	// the save and the facts happen inside one operation
	return u.uow.Do(ctx, func(ctx context.Context) error {
		if err := u.invoices.Save(ctx, issued); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, issued.Events()...)
	})
}

billing/invoice/applications/payment/pay.go

package payment

import (
	"context"

	"billing/invoice/domains/invoice"
)

// dependencies are domain ports and nothing else
type UseCase struct {
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(invoices invoice.Repository, publisher invoice.Publisher) *UseCase {
	return &UseCase{invoices: invoices, publisher: publisher}
}

// load, call the method, save, tell
func (u *UseCase) Run(ctx context.Context, number invoice.Number) error {
	paid, err := u.invoices.ByNumber(ctx, number)
	if err != nil {
		return err
	}

	if err := paid.MarkPaid(); err != nil {
		return err
	}

	if err := u.invoices.Save(ctx, paid); err != nil {
		return err
	}

	// facts leave after the save, not before
	return u.publisher.Publish(ctx, paid.Events()...)
}

billing/invoice/applications/payment/pay.go

package payment

import (
	"context"

	"billing/invoice/domains/invoice"
)

// one more port next to the others: the unit of work
type UseCase struct {
	uow       invoice.UnitOfWork
	invoices  invoice.Repository
	publisher invoice.Publisher
}

func New(
	uow invoice.UnitOfWork,
	invoices invoice.Repository,
	publisher invoice.Publisher,
) *UseCase {
	return &UseCase{uow: uow, invoices: invoices, publisher: publisher}
}

// load, call the method, save, tell
func (u *UseCase) Run(ctx context.Context, number invoice.Number) error {
	return u.uow.Do(ctx, func(ctx context.Context) error {
		paid, err := u.invoices.ByNumber(ctx, number)
		if err != nil {
			return err
		}

		if err := paid.MarkPaid(); err != nil {
			return err
		}

		if err := u.invoices.Save(ctx, paid); err != nil {
			return err
		}

		return u.publisher.Publish(ctx, paid.Events()...)
	})
}

billing/invoice/domains/invoice/load.go

package invoice

import (
	"time"

	"billing/invoice/domains/invoice/vo"
)

// rebuilds the invoice from what is in storage; no facts recorded
func Load(
	number Number,
	customer CustomerID,
	lines []Line,
	total vo.Money,
	dueOn time.Time,
	status Status,
) *Invoice {
	return &Invoice{
		number:   number,
		customer: customer,
		lines:    lines,
		total:    total,
		dueOn:    dueOn,
		status:   status,
	}
}

billing/invoice/domains/invoice/uow.go

package invoice

import "context"

// the port: do the work whole or do not do it at all
type UnitOfWork interface {
	Do(ctx context.Context, work func(ctx context.Context) error) error
}

billing/invoice/infrastructure/postgres/invoices.go

package postgres

import (
	"context"
	"database/sql"
	"time"

	"billing/invoice/domains/invoice"
	"billing/invoice/domains/invoice/vo"
)

// the storage port implementation
type Invoices struct {
	db *sql.DB
}

func NewInvoices(db *sql.DB) *Invoices {
	return &Invoices{db: db}
}

// loads the invoice: the lines come with a separate query
func (r *Invoices) ByNumber(ctx context.Context, number invoice.Number) (*invoice.Invoice, error) {
	var (
		customer string
		minor    int64
		dueOn    time.Time
		status   string
	)

	err := conn(ctx, r.db).
		QueryRowContext(ctx, selectInvoice, string(number)).
		Scan(&customer, &minor, &dueOn, &status)
	if err != nil {
		return nil, err
	}

	lines, err := r.lines(ctx, number)
	if err != nil {
		return nil, err
	}

	// rebuilds the aggregate instead of creating a new one
	return invoice.Load(
		number,
		invoice.CustomerID(customer),
		lines,
		vo.NewMoney(minor),
		dueOn,
		invoice.Status(status),
	), nil
}

// saves the invoice and its lines: two queries, one transaction
func (r *Invoices) Save(ctx context.Context, saved *invoice.Invoice) error {
	db := conn(ctx, r.db)

	if _, err := db.ExecContext(ctx, upsertInvoice, saved); err != nil {
		return err
	}

	_, err := db.ExecContext(ctx, replaceLines, saved)

	return err
}

billing/invoice/infrastructure/postgres/uow.go

package postgres

import (
	"context"
	"database/sql"
)

type txKey struct{}

// a transaction hidden behind a port
type UnitOfWork struct {
	db *sql.DB
}

func NewUnitOfWork(db *sql.DB) *UnitOfWork {
	return &UnitOfWork{db: db}
}

// open, hand over the work, close: one commit per operation
func (u *UnitOfWork) Do(ctx context.Context, work func(ctx context.Context) error) error {
	tx, err := u.db.BeginTx(ctx, nil)
	if err != nil {
		return err
	}

	if err := work(context.WithValue(ctx, txKey{}, tx)); err != nil {
		// an error inside means a full rollback
		_ = tx.Rollback()

		return err
	}

	return tx.Commit()
}

// adapters take the connection here: the transaction sits in ctx
func conn(ctx context.Context, db *sql.DB) interface {
	ExecContext(context.Context, string, ...any) (sql.Result, error)
	QueryRowContext(context.Context, string, ...any) *sql.Row
} {
	if tx, ok := ctx.Value(txKey{}).(*sql.Tx); ok {
		return tx
	}

	return db
}

billing/invoice/infrastructure/postgres/outbox.go

package postgres

import (
	"context"
	"database/sql"
	"encoding/json"

	"billing/invoice/domains/invoice/events"
)

// the publishing port implementation
type Outbox struct {
	db *sql.DB
}

func NewOutbox(db *sql.DB) *Outbox {
	return &Outbox{db: db}
}

// facts do not leave for the bus; they land next to the invoice
func (o *Outbox) Publish(ctx context.Context, facts ...events.Event) error {
	db := conn(ctx, o.db)

	for _, event := range facts {
		body, err := json.Marshal(event)
		if err != nil {
			return err
		}

		// the same transaction as the invoice
		if _, err := db.ExecContext(ctx, insertOutbox, event.FactName(), body); err != nil {
			return err
		}
	}

	return nil
}

Use ← and → to move between steps.