Hexagonal Architecture in Go: Ports and Adapters Explained

internal/
  account/            # the hexagon: domain, use cases, ports
    account.go
    ports.go
    service.go
  adapter/
    httpapi/          # driving adapter
    postgres/         # driven adapter
    email/            # driven adapter
cmd/api/main.go       # wiring

// internal/account/account.go
package account

import (
	"errors"
	"strings"
	"time"
)

var (
	ErrInvalidEmail = errors.New("invalid email")
	ErrInvalidName  = errors.New("name is required")
	ErrEmailTaken   = errors.New("email already registered")
	ErrNotFound     = errors.New("account not found")
)

type Account struct {
	ID        string
	Email     string
	Name      string
	CreatedAt time.Time
}

func New(id, email, name string, now time.Time) (Account, error) {
	email = strings.ToLower(strings.TrimSpace(email))
	name = strings.TrimSpace(name)
	if !strings.Contains(email, "@") {
		return Account{}, ErrInvalidEmail
	}
	if name == "" {
		return Account{}, ErrInvalidName
	}
	return Account{ID: id, Email: email, Name: name, CreatedAt: now}, nil
}

// internal/account/ports.go
package account

import "context"

// API: the driving port. What the outside world can ask the core to do.
type API interface {
	Register(ctx context.Context, email, name string) (Account, error)
	Get(ctx context.Context, id string) (Account, error)
}

// SPI: driven ports. What the core needs from the outside world.
type Repository interface {
	// Create returns ErrEmailTaken if the email already exists.
	Create(ctx context.Context, a Account) error
	FindByID(ctx context.Context, id string) (Account, error)
}

type Notifier interface {
	SendWelcome(ctx context.Context, a Account) error
}

// internal/account/service.go
package account

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

type Service struct {
	repo   Repository
	notify Notifier
	newID  func() string
	now    func() time.Time
}

var _ API = (*Service)(nil) // compile-time check

func NewService(repo Repository, notify Notifier, newID func() string, now func() time.Time) *Service {
	return &Service{repo: repo, notify: notify, newID: newID, now: now}
}

func (s *Service) Register(ctx context.Context, email, name string) (Account, error) {
	a, err := New(s.newID(), email, name, s.now())
	if err != nil {
		return Account{}, err
	}
	if err := s.repo.Create(ctx, a); err != nil {
		return Account{}, fmt.Errorf("create account: %w", err)
	}
	if err := s.notify.SendWelcome(ctx, a); err != nil {
		// The account exists. A failed email shouldn't fail the signup.
		slog.WarnContext(ctx, "welcome email failed", "account", a.ID, "err", err)
	}
	return a, nil
}

func (s *Service) Get(ctx context.Context, id string) (Account, error) {
	return s.repo.FindByID(ctx, id)
}

// internal/adapter/httpapi/handler.go
package httpapi

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

	"github.com/acme/signup/internal/account"
)

type Handler struct{ accounts account.API }

func NewHandler(accounts account.API) *Handler { return &Handler{accounts: accounts} }

func (h *Handler) Routes() *http.ServeMux {
	mux := http.NewServeMux()
	mux.HandleFunc("POST /accounts", h.register)
	mux.HandleFunc("GET /accounts/{id}", h.get)
	return mux
}

type accountResponse struct {
	ID    string `json:"id"`
	Email string `json:"email"`
	Name  string `json:"name"`
}

func (h *Handler) register(w http.ResponseWriter, r *http.Request) {
	var req struct {
		Email string `json:"email"`
		Name  string `json:"name"`
	}
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		http.Error(w, "invalid JSON", http.StatusBadRequest)
		return
	}
	a, err := h.accounts.Register(r.Context(), req.Email, req.Name)
	switch {
	case errors.Is(err, account.ErrInvalidEmail), errors.Is(err, account.ErrInvalidName):
		http.Error(w, err.Error(), http.StatusUnprocessableEntity)
	case errors.Is(err, account.ErrEmailTaken):
		http.Error(w, err.Error(), http.StatusConflict)
	case err != nil:
		http.Error(w, "internal error", http.StatusInternalServerError)
	default:
		writeJSON(w, http.StatusCreated, accountResponse{a.ID, a.Email, a.Name})
	}
}

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

// internal/adapter/postgres/accounts.go
package postgres

import (
	"context"
	"database/sql"
	"errors"

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

	"github.com/acme/signup/internal/account"
)

type AccountRepo struct{ db *sql.DB }

func NewAccountRepo(db *sql.DB) *AccountRepo { return &AccountRepo{db: db} }

func (r *AccountRepo) Create(ctx context.Context, a account.Account) error {
	_, err := r.db.ExecContext(ctx,
		`INSERT INTO accounts (id, email, name, created_at) VALUES ($1, $2, $3, $4)`,
		a.ID, a.Email, a.Name, a.CreatedAt)
	var pgErr *pgconn.PgError
	if errors.As(err, &pgErr) && pgErr.Code == "23505" && pgErr.ConstraintName == "accounts_email_key" {
		return account.ErrEmailTaken
	}
	return err
}

// cmd/api/main.go (imports omitted, including the
// blank import of github.com/jackc/pgx/v5/stdlib)
func main() {
	db, err := sql.Open("pgx", os.Getenv("DATABASE_URL"))
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	svc := account.NewService(
		postgres.NewAccountRepo(db),
		email.NewSMTPNotifier(os.Getenv("SMTP_ADDR")),
		uuid.NewString,
		time.Now,
	)
	log.Fatal(http.ListenAndServe(":8080", httpapi.NewHandler(svc).Routes()))
}

// internal/account/service_test.go
package account_test

type memRepo struct{ byID map[string]account.Account }

func (m *memRepo) Create(_ context.Context, a account.Account) error {
	for _, existing := range m.byID {
		if existing.Email == a.Email {
			return account.ErrEmailTaken
		}
	}
	m.byID[a.ID] = a
	return nil
}

func (m *memRepo) FindByID(_ context.Context, id string) (account.Account, error) {
	a, ok := m.byID[id]
	if !ok {
		return account.Account{}, account.ErrNotFound
	}
	return a, nil
}

type spyNotifier struct{ sent []string }

func (s *spyNotifier) SendWelcome(_ context.Context, a account.Account) error {
	s.sent = append(s.sent, a.Email)
	return nil
}

func TestRegisterRejectsDuplicateEmail(t *testing.T) {
	ctx := context.Background()
	notifier := &spyNotifier{}
	n := 0
	svc := account.NewService(
		&memRepo{byID: map[string]account.Account{}},
		notifier,
		func() string { n++; return fmt.Sprintf("acc-%d", n) },
		func() time.Time { return time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) },
	)

	if _, err := svc.Register(ctx, "[email protected]", "Ana"); err != nil {
		t.Fatalf("first register: %v", err)
	}
	_, err := svc.Register(ctx, " [email protected] ", "Ana again")
	if !errors.Is(err, account.ErrEmailTaken) {
		t.Fatalf("want ErrEmailTaken, got %v", err)
	}
	if len(notifier.sent) != 1 {
		t.Fatalf("want 1 welcome email, got %d", len(notifier.sent))
	}
}