Hexagonal Architecture Separating Domain Logic from Infrastructure

Hexagonal Architecture, also known as Ports and Adapters, is a software design pattern that decouples business logic from infrastructure such as databases, APIs, and UI layers. It promotes flexibility, testability, and maintainability by ensuring the core domain remains independent of external systems.

This article explores the principles, benefits, and implementation of Hexagonal Architecture with practical examples in Go.

Hexagonal Architecture is based on the idea that the application core (domain logic) should not depend on external infrastructure. Instead, external components interact with the domain through ports and adapters.

• Domain Layer - Business logic, independent of frameworks or databases.
• Ports - Interfaces that define how the domain interacts with the outside world.
• Adapters - Implementations of ports that connect infrastructure components like databases or APIs.

graph TD
    A["External API"] --> B["Adapter"]
    B --> C["Port"]
    C --> D["Application Core (Domain)"]
    D --> E["Port"]
    E --> F["Database Adapter"]
    F --> G["Database (SQL)"]

The domain logic remains isolated and communicates with the outside world through well-defined ports.

Let's build a user management system following Hexagonal Architecture principles.

package domain

type User struct {
	ID    string
	Name  string
	Email string
}

The User struct represents the business entity, independent of any database or framework.

package ports

import "example.com/hexagonal/domain"

type UserRepository interface {
	Save(user domain.User) error
	FindByID(id string) (*domain.User, error)
}

The UserRepository interface acts as a port, defining operations that must be implemented by any data storage mechanism.

Now, let's create a PostgreSQL adapter that implements the UserRepository port.

package adapters

import (
	"database/sql"
	"example.com/hexagonal/domain"
	"example.com/hexagonal/ports"
)

type PostgresUserRepository struct {
	db *sql.DB
}

func NewPostgresUserRepository(db *sql.DB) ports.UserRepository {
	return &PostgresUserRepository{db: db}
}

func (r *PostgresUserRepository) Save(user domain.User) error {
	_, err := r.db.Exec("INSERT INTO users (id, name, email) VALUES ($1, $2, $3)", user.ID, user.Name, user.Email)
	return err
}

func (r *PostgresUserRepository) FindByID(id string) (*domain.User, error) {
	var user domain.User
	err := r.db.QueryRow("SELECT id, name, email FROM users WHERE id = $1", id).Scan(&user.ID, &user.Name, &user.Email)
	if err != nil {
		return nil, err
	}
	return &user, nil
}

The PostgresUserRepository acts as an adapter, implementing the UserRepository interface.

package service

import (
	"example.com/hexagonal/domain"
	"example.com/hexagonal/ports"
)

type UserService struct {
	repo ports.UserRepository
}

func NewUserService(repo ports.UserRepository) *UserService {
	return &UserService{repo: repo}
}

func (s *UserService) RegisterUser(user domain.User) error {
	return s.repo.Save(user)
}

func (s *UserService) GetUser(id string) (*domain.User, error) {
	return s.repo.FindByID(id)
}

The UserService contains business logic and interacts with the repository through the UserRepository port, keeping the core independent of the database.

Now, let's create an HTTP API adapter using Gorilla Mux.

package adapters

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

	"example.com/hexagonal/domain"
	"example.com/hexagonal/service"
)

type UserHandler struct {
	service *service.UserService
}

func NewUserHandler(service *service.UserService) *UserHandler {
	return &UserHandler{service: service}
}

func (h *UserHandler) RegisterUser(w http.ResponseWriter, r *http.Request) {
	var user domain.User
	json.NewDecoder(r.Body).Decode(&user)

	err := h.service.RegisterUser(user)
	if err != nil {
		http.Error(w, "Failed to save user", http.StatusInternalServerError)
		return
	}

	w.WriteHeader(http.StatusCreated)
}

func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
	id := r.URL.Query().Get("id")
	user, err := h.service.GetUser(id)
	if err != nil {
		http.NotFound(w, r)
		return
	}

	json.NewEncoder(w).Encode(user)
}

This API adapter allows HTTP clients to interact with the system without affecting the domain logic.

In the main function, we wire the dependencies together.

package main

import (
	"database/sql"
	"log"
	"net/http"

	"example.com/hexagonal/adapters"
	"example.com/hexagonal/service"

	_ "github.com/lib/pq"
	"github.com/gorilla/mux"
)

func main() {
	db, err := sql.Open("postgres", "your-connection-string")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	repo := adapters.NewPostgresUserRepository(db)
	userService := service.NewUserService(repo)
	userHandler := adapters.NewUserHandler(userService)

	router := mux.NewRouter()
	router.HandleFunc("/users", userHandler.RegisterUser).Methods("POST")
	router.HandleFunc("/users", userHandler.GetUser).Methods("GET")

	log.Println("Server running on port 8080")
	log.Fatal(http.ListenAndServe(":8080", router))
}

• Separation of Concerns - Business logic is independent of infrastructure.
• Testability - The domain logic can be tested without external dependencies.
• Flexibility - Easy to swap adapters (e.g., replace PostgreSQL with MongoDB).
• Scalability - Encourages modular and maintainable code.

Hexagonal Architecture helps in decoupling domain logic from infrastructure, making applications more maintainable and flexible. By structuring an application with ports and adapters, developers can ensure that the core logic remains clean, testable, and reusable.

This guide demonstrated how to implement Hexagonal Architecture in Go with a user management system, using database and API adapters. By following this approach, you can build scalable, well-structured applications that are easy to extend and maintain.