hexagonal

Hexagonal Architecture (Ports and Adapters)

Hexagonal Architecture aims to create a loosely coupled application component that can easily connect to their software environment by "ports" and "adapters". It treats the database, the web UI, and external APIs as interchangeable "details" (infrastructure).

When to Use

• Core Business Logic Isolation: Keeping domain models completely pure and independent of database choices, web frameworks, and messaging tools.
• Pluggable Architecture: Systems where components (e.g. storage engine, notification providers, payment gateways) must be easily swappable.
• Automated Regression Testing: Running full business scenario tests with fast, zero-dependency in-memory adapters.
• Microservice Reusability: Allowing the exact same business core to be driven by an HTTP REST controller, a gRPC server, and a CLI simultaneously.

Quick Start

// --- CORE (Inside the Hexagon) ---

// Port (Driver Port - Input)
type UserService interface {
    Register(name string) error
}

// Port (Driven Port - Output)
type UserRepository interface {
    Save(user User) error
}

// Application Service (Implementation)
type UserServiceImpl struct {
    repo UserRepository
}

func (s *UserServiceImpl) Register(name string) error {
    return s.repo.Save(User{Name: name})
}

// --- ADAPTERS (Outside the Hexagon) ---

// Driving Adapter (REST API)
func HandleRegister(w http.ResponseWriter, r *http.Request, svc UserService) {
    svc.Register(r.FormValue("name"))
}

// Driven Adapter (Postgres)
type PostgresRepo struct { db *sql.DB }
func (r *PostgresRepo) Save(u User) error { ... }

Core Concepts

Ports and Adapters Topology

The application core sits at the center; Driving Ports receive input from the outside world; Driven Ports communicate with infrastructure:

[ HTTP Controller ] ──(Driving Port)──→ [ APPLICATION CORE ] ──(Driven Port)──→ [ Postgres Adapter ]
[ CLI Command ]     ──(Driving Port)──→ [ APPLICATION CORE ] ──(Driven Port)──→ [ Mock DB Adapter ]