---

name: go-service-hexagonal description: Define, review, and scaffold Go service directory structures using hexagonal (ports-and-adapters / “jexagonal”) architecture and Go best practices. Use when creating or refactoring Go services, deciding package boundaries, organizing cmd/internal/api/config/deploy/migrations, or choosing layouts for common service types (HTTP REST API, gRPC API, async worker/consumer, scheduled job, CLI, multi-binary repos).

Go Service Hexagonal

Workflow

1) Choose the repo shape

• Use single-service repo when one deployable dominates the repo.
• Use multi-binary repo when multiple deployables share a domain and are released together (API + worker + migrator).
• Use monorepo when many services share tooling but keep each service isolated under <service>/cmd/<service>-<binary> and <service>/internal/....

2) Choose the service kind

• HTTP REST/JSON API → use references/layout-http-rest.md
• gRPC API → use references/layout-grpc.md
• Worker/consumer/scheduler/job → use references/layout-worker.md
• CLI (ops tools, admin, local runner) → use references/layout-cli.md

3) Apply hexagonal (ports-and-adapters) boundaries

• Put business rules in internal/domain.
• Put use cases in internal/app and define inbound ports in internal/interface.
• Define outbound ports (interfaces to DB, queues, HTTP clients) in internal/adapter.
• Implement inbound adapters in internal/interface/* (primary) and outbound adapters in internal/adapter/* (secondary).
• Choose a settings mode: none (defaults only), env (env-only), or config (env + optional config file via Koanf, env overrides config). Use internal/interface/options only for config mode.
• Perform all wiring in a single composition root: internal/bootstrap.Compose(...) and keep cmd/* thin.

Use references/architecture-rules.md as the dependency rulebook.

4) Refactor an existing project

• Read references/refactor-workflow.md.
• For minimal, necessary tests during refactors, read references/refactor-testing.md.
• Create a refactor plan using references/refactor-plan-template.md and agree on it with the user before making changes.
• Execute the plan in small, explicit steps and confirm after each step.
• Track the plan in a checkboxed REFACTORING.md at repo root and mark completed items as you finish them.

Scaffolding

Run the scaffolder to generate a starting tree plus minimal compileable stubs:

python3 scripts/scaffold_hex_service.py --root <repo> --service <name> --kinds http,worker

Pick a settings mode:

• Defaults only: --settings none
• Env only (default): --settings env
• Env + config file (Koanf): --settings config

Example (config mode):

python3 scripts/scaffold_hex_service.py --root <repo> --service <name> --kinds http --settings config

Config files (when enabled) support json/yaml/toml with keys: http_addr, pprof_addr, pprof_port, log_level. If the config file has no extension, TOML is assumed. Environment values override config values when both are set.

HTTP scaffolding defaults to Echo. For explicit Echo:

python3 scripts/scaffold_hex_service.py --root <repo> --service <name> --kinds http --http-framework echo

For a pure net/http baseline:

python3 scripts/scaffold_hex_service.py --root <repo> --service <name> --kinds http --http-framework nethttp

HTTP scaffolds include GET /health/live and GET /health/ready, plus request logging using Logrus (github.com/sirupsen/logrus).

Optional (opt-in) HTTP debug endpoints:

• --http-pprof adds handlers under GET /debug/pprof/* (pprof index + profiles).
• --http-trace adds GET /debug/pprof/trace (execution trace).
• These run on a separate debug HTTP server and are activated only when PPROF_PORT is set (e.g. PPROF_PORT=6060); optionally set PPROF_ADDR to change the bind address (default 127.0.0.1).
• The handler mux is scaffolded as a dedicated inbound adapter: internal/interface/debughttp.

For new projects, if --module is omitted the module path defaults to the <repo> folder name (no github.com/... assumption). If go.mod is created (new project), the scaffolder runs go mod tidy to fetch dependencies (Echo + Logrus). Use --skip-deps to skip.

Generated projects include required README.md, AGENTS.md, and Makefile at repo root. When HTTP is scaffolded, the project also includes test/health_test.go.

Then edit the generated packages to match your domain and ports.

Reference Index

Read references/index.md and then open only the layout file(s) you need for the chosen service kind.