Hexagonal Architecture in Go

Detect the repo's layout first

get_repo_tree   # look for domain/port/application/adapter-named folders

Follow the repository's own names for these folders (internal/core, internal/service, whatever it already uses) — don't rename them to match this skill. Never restructure a repository that is not hexagonal in a feature task. If the repo has no layering at all, follow its existing flat/package-by-feature style instead of introducing hexagonal boundaries unasked.

Layers

• Domain (innermost): entities, value types, domain errors. Imports nothing from the outer layers — no Fiber, no pgx, no HTTP, no JSON tags driving behavior.
• Ports: interfaces (e.g. internal/port) describing what the application needs (repositories, clients) and offers (services).
• Application: use-case services orchestrating domain logic through ports. Depends on domain and ports only.
• Adapters: implementations at the edge — HTTP handlers, PostgreSQL repositories, external clients. Adapters import inward; nothing imports an adapter.

Rules

• Dependency injection via constructors: NewService(store port.Store, ...). No globals, no init()-time wiring (Uber: "Avoid init()", "Exit in Main").
• Cross-layer calls go through ports. A service never touches pgx directly; a handler never contains business logic.
• New behavior starts with the port interface and its domain types, then the service, then the adapter — the test for the service uses a fake or mock of the port (mockery-suite-tests).
• When adding a dependency, ask: does the domain need to know this exists? If yes, model it as a port; if no, keep it inside the adapter.
• Verify interface compliance at compile time (Uber): var _ port.TaskStore = (*PGTaskStore)(nil) next to the adapter's constructor — a missing method fails the build, not a runtime wiring panic.
• Copy slices and maps at boundaries (Uber) — a port implementation that hands back its internal slice lets the caller mutate state it doesn't own.

Worked Example: "Archive a project"

1. Domain errors: domain.ErrNotFound, domain.ErrConflict (sentinel errors the adapters translate into and the handler's central mapper translates out of).
2. Port: port.ProjectStore with Archive(ctx context.Context, id uuid.UUID) error.
3. Service + test: the use case calls the port; the test uses the port's mock/fake — no database in this test.
4. Postgres adapter: translates driver errors into domain errors — errors.Is(err, pgx.ErrNoRows) → domain.ErrNotFound; pgErr.Code == "23505" → domain.ErrConflict. This translation happens in the adapter, never in the handler or service.
5. Compile-time check: var _ port.ProjectStore = (*PGProjectStore)(nil) beside the constructor.
6. Handler: maps through the one central error handler (fiber-rest-api) — no case-by-case mapping here.

Transactions across ports

Model the transaction boundary as a port, not a leaked *sql.Tx/pgx.Tx: port.TxRunner with WithinTx(ctx context.Context, fn func(ctx context.Context) error) error. The Postgres adapter puts the pgx.Tx into the returned ctx; repository adapters use the tx-in-context when present, falling back to the pool otherwise. The transaction boundary belongs to the use case (application layer), which decides what must commit together — never to a repository method.

Wiring

Constructors are called from main/a wiring package only — no package-level mutable globals holding dependencies (Uber "Avoid Global State").

Verify the import direction

go list -deps ./internal/domain/... ./internal/application/... | grep -E '/internal/adapter|gofiber|jackc/pgx|database/sql'

Adjust the paths to the repo's actual package names. Must print nothing — any hit is a boundary violation.

Smell Checklist

• A framework/driver import (gofiber/fiber, jackc/pgx, database/sql) anywhere under domain or application → boundary violation.
• A struct with both business rules and SQL strings → split into service + repository adapter.
• A handler longer than ~30 lines → logic belongs in the application service.
• A port method returning a framework type (*fiber.Ctx, *sql.Rows) instead of domain types.
• A repository adapter test that mocks the SQL driver instead of running against real Postgres.