go-hexagonal-architecture
Use this when designing the internal package layout of a Go microservice, defining port interfaces for repositories/messaging/external integrations, implementing PostgreSQL/NATS/third-party adapters,
SKILL.mdskills/go-hexagonal-architecture/SKILL.md
GitHubGo Hexagonal Architecture
Standardizes the internal package layout for every microservice using hexagonal (ports and adapters) architecture. Domain logic stays isolated from infrastructure; all external dependencies flow through port interfaces.
When to Activate
- When designing the internal package structure of a Go microservice
- When defining port interfaces for repositories, messaging, or external integrations
- When implementing adapters for PostgreSQL, NATS, or third-party services
- When wiring application services with dependency injection
- When reviewing service structure for proper domain isolation
- Used by: component-designer, simulated-senior-developer, simulated-tech-lead
Package Structure
Every microservice follows this canonical layout. Replace <service-name> and <entity> with your domain (e.g., order-service/order, patient-service/patient, account-service/account):
Domain Service Layout (NATS-primary inbound)
For all domain services, the primary inbound adapter is NATS (subscriptions for events, request-reply handlers for queries). HTTP inbound adapters are NOT used for inter-service communication. Only the API Gateway has HTTP inbound adapters for business endpoints.
services/<service-name>/
├── cmd/
│ └── server/
│ └── main.go # Wiring, config, graceful shutdown
├── internal/
│ ├── domain/
│ │ ├── model/
│ │ │ ├── <entity>.go # Domain entities, value objects
│ │ │ └── rule.go
│ │ ├── event/
│ │ │ └── <entity>_events.go # Domain events
│ │ └── service/
│ │ └── <entity>_svc.go # Domain services (pure logic, no I/O)
│ ├── application/
│ │ ├── command/
│ │ │ └── create_<entity>.go # Command handlers (use-case orchestration)
│ │ ├── query/
│ │ │ └── get_<entity>.go # Query handlers
│ │ └── dto/
│ │ └── <entity>_dto.go # Input/output DTOs for the application layer
│ ├── ports/
│ │ ├── inbound/
│ │ │ └── <entity>_api.go # Inbound port interfaces
│ │ └── outbound/
│ │ ├── <entity>_repo.go # Repository port
│ │ ├── event_pub.go # Messaging port (NATS publish)
│ │ └── service_query.go # Inter-service query port (NATS request-reply)
│ └── adapters/
│ ├── inbound/
│ │ └── nats/
│ │ ├── subscriber.go # NATS event subscriber adapter
│ │ └── responder.go # NATS request-reply responder adapter
│ └── outbound/
│ ├── dal/
│ │ └── client.go # DAL client adapter (NATS→DAL for all DB ops)
│ ├── cache/
│ │ └── l1_cache.go # freecache L1 adapter
│ ├── nats/
│ │ ├── event_pub.go # NATS publisher adapter
│ │ └── requester.go # NATS request-reply client adapter
│ └── email/
│ └── notifier.go # Email adapter (via NATS to notification service)
├── migrations/
│ ├── 000001_create_<entities>.up.sql
│ └── 000001_create_<entities>.down.sql
└── config/
└── config.go # Service-specific config struct
API Gateway Layout (HTTP-primary inbound)
Only the API Gateway has HTTP inbound adapters for business endpoints. It translates HTTP requests into NATS request-reply calls to domain services.
services/api-gateway/
├── cmd/server/main.go
├── internal/
│ ├── adapters/
│ │ ├── inbound/
│ │ │ └── http/
│ │ │ └── handler.go # HTTP adapter (external client endpoints)
│ │ └── outbound/
│ │ └── nats/
│ │ └── requester.go # NATS request-reply to domain services
│ ├── ports/
│ │ ├── inbound/
│ │ │ └── gateway_api.go # HTTP inbound port
│ │ └── outbound/
│ │ └── service_client.go # Inter-service query port (NATS)
│ └── middleware/ # Auth, rate limit, tenant extraction
└── config/config.go
Data Access Layer (DAL) Service Layout (PostgreSQL-primary)
The DAL service is the SOLE PostgreSQL client. It receives NATS requests from entity services, compiles QueryStruct → SQL, executes queries, resolves cross-joins, encodes MsgPack, and manages L2 Dragonfly cache.
services/data-access-layer/
├── cmd/server/main.go # pgxpool + Dragonfly + NATS + OTel wiring
├── internal/
│ ├── domain/
│ │ └── querybuilder/
│ │ ├── types.go # QueryStruct, Pagination, CompiledQuery
│ │ └── compiler.go # Compile(), EnforcePagination()
│ ├── application/
│ │ ├── handler_get.go # GET-by-ID: L2 check → SQL → encode
│ │ ├── handler_list.go # List: compile → execute → cross-join → encode
│ │ ├── handler_analytics.go # Analytics: force_duckdb → execute → encode
│ │ ├── handler_create.go # Insert → invalidate L2 → publish event
│ │ ├── handler_update.go # Update (optimistic lock) → invalidate
│ │ ├── handler_delete.go # Soft delete → invalidate
│ │ └── handler_batch.go # Transactional batch operations
│ ├── ports/
│ │ ├── inbound/
│ │ │ └── dal_handler.go # NATS request handler interface
│ │ └── outbound/
│ │ ├── pool_manager.go # pgxpool PoolManager interface
│ │ ├── cache.go # L2 Dragonfly cache interface
│ │ └── event_pub.go # Cache invalidation event publisher
│ └── adapters/
│ ├── inbound/
│ │ └── nats/
│ │ └── subscriber.go # NATS QueueSubscribe for DAL requests
│ └── outbound/
│ ├── postgres/
│ │ ├── pool_manager.go # pgxpool shared pool per app-database
│ │ ├── schema.go # AcquireForTenant, sanitizeSchema
│ │ ├── executor.go # SQL execution, scanToMaps
│ │ └── analytics.go # DuckDB session setup
│ ├── dragonfly/
│ │ └── cache.go # Dragonfly L2 cache adapter (go-redis)
│ ├── crossjoin/
│ │ └── resolver.go # EntityResolver, ResolveCrossJoins worker pool
│ └── encoding/
│ └── columnar.go # EncodeColumnar, DecodeColumnar MsgPack
├── migrations/ # DAL owns ALL migrations for all entity tables
└── config/config.go # PostgreSQL DSN, Dragonfly URL, NATS URL
DAL is the ONLY service with adapters/outbound/postgres/. Entity services
have adapters/outbound/dal/ (NATS client) instead.
Package Rules
| Rule | Rationale |
|---|---|
domain/ imports NOTHING outside domain/ |
Domain must be pure, testable without infrastructure |
application/ imports domain/ and ports/ only |
Orchestrates use cases via port interfaces |
ports/ imports domain/ types only |
Interfaces reference domain models, not adapter types |
adapters/ imports ports/, domain/, and external libs |
Adapters implement ports with real infrastructure |
cmd/ wires everything together |
The composition root, no business logic |
Port Interface Design
Repository Port
// internal/ports/outbound/<entity>_repo.go
package outbound
import (
"context"
"github.com/yourorg/<service-name>/pkg/dal"
)
// OrderQuerier defines data access operations routed through DAL.
// Every method ultimately sends a NATS request to the data-access-layer service.
type OrderQuerier interface {
GetByID(ctx context.Context, id string) ([]byte, error)
List(ctx context.Context, qs dal.QueryStruct) ([]byte, error)
Create(ctx context.Context, data map[string]any) ([]byte, error)
Update(ctx context.Context, id string, data map[string]any, version int) error
Delete(ctx context.Context, id string) error
}
Messaging Port (NATS Publish)
// internal/ports/outbound/event_pub.go
package outbound
import "context"
// EventPublisher abstracts the messaging infrastructure.
// Implementations target NATS JetStream in this project.
type EventPublisher interface {
Publish(ctx context.Context, subject string, payload []byte) error
PublishAsync(ctx context.Context, subject string, payload []byte) error
}
Inter-Service Query Port (NATS Request-Reply)
// internal/ports/outbound/service_query.go
package outbound
import "context"
// ServiceQuerier abstracts NATS request-reply calls to other services.
// This replaces HTTP clients and gRPC stubs for inter-service queries.
type ServiceQuerier interface {
Query(ctx context.Context, subject string, request []byte) ([]byte, error)
}
External Service Port (via NATS)
// internal/ports/outbound/notification.go
package outbound
import (
"context"
"github.com/google/uuid"
)
// Notifier abstracts notification delivery via NATS to the notification service.
// No direct HTTP calls to other services -- communication goes through NATS.
type Notifier interface {
SendEntityCreated(ctx context.Context, tenantID uuid.UUID, entityID uuid.UUID) error
SendDeadlineApproaching(ctx context.Context, tenantID uuid.UUID, entityID uuid.UUID) error
}
Adapter Implementation
Adapters implement port interfaces with real infrastructure dependencies.
// internal/adapters/outbound/dal/client.go
package dal
import (
"github.com/coocood/freecache"
"github.com/yourorg/<service-name>/internal/ports/outbound"
"github.com/yourorg/<service-name>/pkg/dal"
)
// Compile-time interface check.
var _ outbound.OrderQuerier = (*OrderDALClient)(nil)
// OrderDALClient implements OrderQuerier via NATS request-reply to DAL.
type OrderDALClient struct {
dalClient dal.Client // pkg/dal NATS client
l1Cache *freecache.Cache
}
Application Service Layer
Application services orchestrate use cases by composing domain logic with port calls.
// internal/application/command/create_order.go
package command
import (
"context"
"github.com/vmihailenco/msgpack/v5"
"fmt"
"github.com/yourorg/<service-name>/internal/domain/model"
"github.com/yourorg/<service-name>/internal/ports/outbound"
)
// CreateOrderHandler orchestrates order creation.
type CreateOrderHandler struct {
repo outbound.OrderRepository
publisher outbound.EventPublisher
}
// NewCreateOrderHandler returns a handler wired to its ports.
func NewCreateOrderHandler(repo outbound.OrderRepository, pub outbound.EventPublisher) *CreateOrderHandler {
return &CreateOrderHandler{repo: repo, publisher: pub}
}
// Handle executes the create-order use case.
func (h *CreateOrderHandler) Handle(ctx context.Context, cmd model.CreateOrderCommand) (*model.Order, error) {
order := model.NewOrder(cmd)
if err := h.repo.Create(ctx, order); err != nil {
return nil, fmt.Errorf("creating order: %w", err)
}
payload, err := msgpack.Marshal(order)
if err != nil {
return nil, fmt.Errorf("marshalling order event: %w", err)
}
subject := fmt.Sprintf("tenant.%s.order.created", order.TenantID)
if err := h.publisher.Publish(ctx, subject, payload); err != nil {
return nil, fmt.Errorf("publishing order.created: %w", err)
}
return order, nil
}
Composition Root (cmd/main.go)
// cmd/server/main.go
package main
import (
"context"
"log"
"os/signal"
"syscall"
"time"
"github.com/coocood/freecache"
dalclient "github.com/yourorg/<service-name>/internal/adapters/outbound/dal"
natspub "github.com/yourorg/<service-name>/internal/adapters/outbound/nats"
"github.com/yourorg/<service-name>/internal/application/command"
"github.com/yourorg/<service-name>/pkg/dal"
)
func main() {
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
// L1 Cache (in-process, for GET-by-ID)
l1Cache := freecache.NewCache(100 * 1024 * 1024) // 100MB
// DAL client (all DB operations via NATS to data-access-layer)
dc := dal.NewClient(nc, dal.WithTimeout(5*time.Second))
defer dc.Close()
repo := dalclient.NewOrderDALClient(dc, l1Cache)
pub := natspub.NewPublisher( /* nats conn */ )
handler := command.NewCreateOrderHandler(repo, pub)
_ = handler // wire into NATS inbound adapters
<-ctx.Done()
}
Examples
GOOD
// Domain model depends on nothing external.
// internal/domain/model/order.go
package model
import (
"time"
"github.com/google/uuid"
)
// Order represents the core order entity.
type Order struct {
ID uuid.UUID
TenantID uuid.UUID
CustomerID uuid.UUID
Status string
CreatedAt time.Time
UpdatedAt time.Time
}
BAD
// WRONG: Domain model imports infrastructure (pgx).
package model
import (
"github.com/jackc/pgx/v5"
)
type Order struct {
Row pgx.Row // Domain leaks infrastructure detail
}
GOOD
// Compile-time interface satisfaction check.
var _ outbound.OrderRepository = (*OrderRepo)(nil)
BAD
// WRONG: No compile-time check. A broken adapter is only caught at runtime.
type OrderRepo struct{}
// Missing: var _ outbound.OrderRepository = (*OrderRepo)(nil)
Common Mistakes
Domain imports infrastructure packages -- The
domain/package must never importpgx,nats,net/http, or any adapter library. If domain code needs I/O, define a port interface inports/outbound/and inject the adapter.Business logic in adapters -- Adapters (NATS subscribers, request-reply responders) should only translate between external formats and application-layer calls. Move validation, orchestration, and rules into
application/ordomain/service/.Skipping compile-time interface checks -- Always add
var _ PortInterface = (*Adapter)(nil)in every adapter file. Without this, interface drift goes undetected until runtime.Putting wiring logic in application services -- Constructor calls, config parsing, and connection setup belong in
cmd/. Application services receive fully constructed dependencies through their constructors.Missing TenantID in port method signatures -- Every method that queries or mutates data must accept tenant context. A repository method without
tenantIDbreaks tenant isolation.Using HTTP inbound adapters for inter-service communication -- Domain services must NOT have HTTP inbound adapters for business endpoints. Only the API Gateway has HTTP inbound adapters. Domain services use NATS inbound adapters (subscriptions for events, responders for request-reply queries).
Using pgxpool in entity services -- Entity services communicate with DAL via NATS. Only the DAL service imports pgxpool.