Hexagonal Architecture with Go

Full code implementation: github.com/yehezkiel1086/go-gin-hexa-archi

Definition: Creating your app without either UI or DB to be able to run automated regression-tests against the app, work when db becomes unavailable, and link apps together without user involvement.

The idea of seamlessly swapping infrastructures with minimal code changes

• Hexagonal archi also known as Ports & Adapters archi
• A type of clean architecture
• Popularized by Alistair Cockburn
• Great way of organizing software to make apps easy to work on and can change without breaking
• To separate the app's core business logic from external stuffs like DB, UI, and other external services
• Promotes a clean and modular structures to make it easier to test, maintain and scale

Core

• Heart of the app
• contains the essential business logic and rules of the application
• Should be independent of any external technologies or frameworks, making it highly portable and reusable
• “ports” and “adapters” dictates how the “core” interacts with the external components

Examples:

• processing orders
• managing user accounts
• and performing all the tasks of the application is designed for

Ports

• Think of ports as contracts or interfaces
• Define how the app communicates with external systems or services
• Belongs to the core (bc core defines which actions required to achieve business logic goals)

Examples:

• specify the rules for connecting to a database
• interacting with other web services
• handling user interfaces

Adapters

• The ones implementing the contracts or interfaces defined by ports
• They handle technical details

Responsible for making sure the app can interact to:

• dbs
• web services
• etc

Driver Actors

• initiators of communication with the core
• they reach out to the core to request specific services

Examples:

• HTTP request
• CLI

Driven Actors

• The ones triggered by the core
• when core needs something from external services, it sends a req to the adapter to perform some action

Examples:

• when core needs to store data in postgres DB, it triggers communication with the postgres client to execute INSERT query — here the core initiates the communication

Tech Stacks Example

• Gin — handling HTTP requests and responses
• PostgreSQL — database
• PGX — DB driver
• Redis — caching
• go-redis — go library to implement Redis

(Source: medium.com)

• Hexagonal Architecture is depicted as hexagon
• The core (center) houses domain and service contains business logic
• driver port (left of core) as entry point for driver adapter
• 2 driven port (right of core) act as the gate for core to interact with the driven adapter
• adapters (around the core) bridge the core and external world: HTTP adapter (left) handles incoming HTTP requests; db adapter (right) connects to Postgres; cache adapter works with Redis
• driver actors (left) serves as HTTP server (Nginx) and driven actors (right) responding to core requests (postgres & Redis). They are outside the application.

Project Structure

.
├── bin
├── cmd
│   └── http
├── docs
└── internal
    ├── adapter
    │   ├── cache
    │   │   └── redis
    │   ├── handler
    │   │   └── http
    │   ├── repository
    │   │   └── postgres
    │   │       └── migrations
    │   └── token
    │       └── paseto
    └── core
        ├── domain
        ├── port
        ├── service
        └── util

21 directories

• bin: directory to store compiled executable binary.
• docs: directory to store project's documentation, such as swagger static files.
• cmd: directory for main entry points or commands of the application. The http sub-directory holds the main HTTP server entry point.
• internal: directory for containing application code that should not exposed to external packages.
• core: directory that contains the central business logic of the application. Inside it there are 4 sub-directories.
  • domain: directory that contains domain models/entities representing core business concepts.
  • port: directory that contains defined interfaces or contracts that adapters must follow.
  • service: directory that contains the business logic or services of the application.
  • util: directory that contains utility functions that reused in the service package.
• adapters: directory for containing external services that will interact with the core of application. There are 4 external services used in this application.
  • handler/http: directory that contains HTTP request and response handler.
  • repository/postgres: directory that contains database adapters for PostgreSQL.
  • cache/redis: directory that contains cache adapters for Redis.
  • token/paseto: directory that contains token generation and validation adapters using Paseto.