Hexagonal Architecture

1.1. Hexagonal Architecture in a nutshell

1.1.1. It’s all about business logic

• explicit separation between what code is internal to the application and what is external
  

1.2. Ports & Adapters

1.2.1. Ports

• A port is an input to your application and the only way the external world can reach it
  
• Examples:
  
  • HTTP/gRPC servers handling requests from outside to your business application
    
  • CLI commands doing something with your business use cases
    
  • Pub/Sub message subscribers
    

1.2.2. Adapters

• Adapters are something that talk to the outside world
  
• you have to adapt your internal data structures to what it’s expected outside
  
• Examples
  
  • SQL queries
    
  • HTTP/gRPC clients
    
    • file readers/writers
      
• Some distinguish between
  
  • primary/driving adapters
    
  • secondary/driven adapters
    

1.2.3. Application logic/core

• a layer that glues together other layers
  
• also known as the place where “use cases” live at
  
• this is what our code is supposed to do (it’s the main application)
  
• the application logic depends only on own domain entities
  
  • if you cannot say which database is used for storing entities, that’s a good sign
    
  • if you cannot say which URLs it calls for doing authentication, that’s a good sign
    
  • in general: this layer is “free” of any concrete implementation details
    

1.3. Language-agnostic implementation

• I’ll describe use cases for a concrete problem
  
• There are several actors involved
  
  • uploader
    
  • product manager
    
• I’ll abstractions to define relationships between
  
  • use cases and
    
  • concrete implementations
    

1.3.1. Uploader: use case description

As an uploader I’d like to upload documents to some infrastructure. After successful upload I’d like to get a link I can share with my friends.
– Uploader

Easy! Some observations:

• the uploader doesn’t mention where (storage) the documents should be uploaded to
  
• the uploader doesn’t mention how he/she would like to upload documents
  
  • via web client?
    
  • via mobile phone?
    
  • via CLI?
    

1.3.2. Product Manager: use case description

As a product manager I’d like to see how many documents each uploader uploads and how many times he/she shares the link.
– Product Manager

Also easy! Again some observations:

• PM doesn’t mention where the metrics should be sent to
  
• PM doesn’t mention how she would like to view the metrics
  
  • Via Web?
    
  • On her smartphone?
    
  • Using the CLI?
    

1.3.3. Use abstractions

• post-pone decision about concrete implementation details / concrete technologies
  
• focus on business cases and use abstractions (aka interfaces) whenever possible
  
• separate concerns
  
  • apply information hiding
    
  • use SOLID
    
• you can apply this on different levels
  
  • structures
    
  • namespaces
    
  • modules
    
  • packages
    
  • microservices
    
  • just keep related things within a boundary
    
    • in DDD language: boundary context
      

2.1. Software Architecture: High-Level (explanations)

• The Business Domain ❶ contains
  
  • Entities (there is only Document)
    
  • Services (DocumentUploadService)
    
  • Repositories (DocumentStorageRepository and DocumentMetricsRepository)
    
    • basically interfaces to be implemented by the Secondary Adapters ❸
      
• The Secondary (Driven) Adapters implement
  
  • the repositories/interfaces defined in the Business Domain ❶
    
• The Primary (Driving) Adapters ❷ use the Services
  
  • a CLI could implement the DocumentUploadService for the terminal
    
  • a HTTP server could serve the DocumentUploadService via HTTP
    

3.1. Entities

class Document ():                        ❶
	"""A document is an entity"""
	def __init__(self, path: FilePath):
		self._file_path = path            ❷

	def meta(self):
	"""Display meta information about the file"""
		print("Some information")

3.2. Services

3.2.1. UploadDocumentService

class UploadDocumentService:           ❶
	"""Upload a document to storage repository"""

	def __init__(
		self,
		storage_repository: DocumentStorageRepository,
		metrics_repository: DocumentMetricsRepository,
	):
		self._storage_repo: DocumentStorageRepository
		self._metrics_repo: DocumentMetricsRepository

	def upload_document(self, document: Document):   ❷
		self._storage_repository(document)
		self._metrics_repo.send_metrics()

4.1. Storage

from import abc import ABC, abstractmethod

class DocumentStorageRepository(ABC):      ❶
	""" Driven port defining an interface for storing documents """
	@abstractmethod
	def save(self, path: FilePath):
		pass

	@abstractmethod
	def search(self, uuid: uuid):
		pass

	@abstractmethod
	def delete(self, uuid: uuid):
		pass

4.2. Metrics

from import abc import ABC, abstractmethod

class DocumentMetricsRepository(ABC):    ❶
""" Driven port defining an interface for sending metrics about documents"""
@abstractmethod
	def send_metrics(self):
		pass

5.1. Primary / driving

5.1.1. HTTP handler

The handler only depends on entities and services.

# HTTP controller
from flask import Flask, request
from domain.services import UploadDocumentService
from domain.entities import Document

app = Flask(__name__)

class HTTPController:
    def __init__(self, upload_service: UploadDocumentService):  ❶
	    self.upload_service = upload_service

	@app.route(self, '/upload', methods=['POST'])
	def upload_document():
		"""Uploads a document using DocumentUploadService """
		# Create a document object
		doc = entities.Document(request.form.get("document_path"))
        self.upload_service.upload_document(doc)                ❷

5.1.2. CLI handler

The handler only depends on entities and services.

# Simpl CLI controller
import sys, getopt
from domain.services import UploadDocumentService
from domain.entities import Document

class CLIController:
    def __init_(self, arguments, upload_service: UploadDocumentService):  ❶
	    self.args = arguments
		self.upload_service = upload_service

	def upload(self):
	   inputfile = ''
	   try:
		  opts, args = getopt.getopt(self.args,"hi:",["ifile="])
	   except getopt.GetoptError:
		  print 'cli.py -i <inputfile>'
		  sys.exit(2)

	   for opt, arg in opts:
		  if opt == '-h':
			 print 'cli.py -i <inputfile>'
			 sys.exit()

		  elif opt in ("-i", "--ifile"):
			 inputfile = arg


	   # Create document object
	   doc = Document(inputfile)
	   service.upload_service.upload_document(doc)                   ❷

5.2. Secondary / driven

5.2.1. S3

from domain.entities import Document

class S3StorageRepository:
    """Implements DocumentStorageRepository """
	def __init__(self):
	    # Initiate here connection to AWS S3
		self.s3_conn = ...

	def save(self, doc: Document):                   ❶
	    # Read file contents
		content = get_file_content(doc)
		self.s3_conn.create_new_object(content, ...) ❷

	def search(): List[Document]                     ❸
	    # Search in S3 buckets and return list of documents
		doc_list = []
		for f in results:
		    # Create a document
			doc = Document(f.path())
			doc_list.append(doc)
		return doc_list
	...

5.2.2. ELK

from domain.entities import Document

class ELKMetricsRepository:
    """Implements DocumentMetricsRepository """
	def __init__(self):
	    # Initiate here connection to ELK stack
		self.elk_conn = ...             ❶

    def send_metrics():
	    self.elk_conn.send_data(...)    ❷