#Arquitectura #Frameworks #redes

Hexagonal Architecture: Beyond Traditional Layers

2025-11-22 · Benja

Hexagonal Architecture - Developed by Alistair Cockburn, to solve the fundamental problem of technological coupling that affects most enterprise projects.

Hexagonal Architecture: Beyond Traditional Layers (and Organized Chaos)

Core idea: separate business logic from the surrounding technology (frameworks, databases, protocols, etc.). The domain rules — everything else obeys.

🎯 Introduction: Separating Business from the Tech Circus

Hexagonal Architecture — also known as Ports and Adapters — is not just another fancy way of saying "layers". It represents a shift in how we structure applications that must survive years, multiple frameworks, and several architectural "refactors of faith".

Proposed by Alistair Cockburn, it tackles a recurring issue: business logic polluted by infrastructure concerns such as controllers, ORMs, SDKs, message brokers, and databases.

Typical problem in classical architectures

Controllers mixing validation, SQL and business rules.
Use cases coupled to specific frameworks.
Tests that require half your infrastructure stack to run.
Refactors scarier than deleting production logs.

The domain lives at the center, isolated, pure and sovereign. Everything else orbits around it.

🏗️ Fundamental Concepts

Domain: Business rules, framework-agnostic.
Ports: Contracts defining what the system needs or exposes.
Adapters: Implementations that connect to the outside world.

⚡ Practical Implementation: Order Management System

src/
├── domain/
│   ├── entities/
│   ├── value-objects/
│   ├── repositories/
│   └── services/
├── application/
│   ├── use-cases/
│   ├── ports/
│   └── dtos/
├── infrastructure/
│   ├── web/
│   ├── persistence/
│   └── messaging/
└── main.ts

🧠 Domain Layer

The domain holds the intelligence. Rules are self-contained and resilient.

🧩 Value Objects

Encapsulate validation and immutability for atomic concepts like Email or Money.

🚪 Ports

Interfaces defining system interaction points without exposing implementation.

🎯 Use Cases

Coordinate domain operations and enforce workflows.

🧱 Adapters

Concrete implementations: REST controllers, ORM repositories, external APIs.

🧪 Testing

Fast domain-level tests
Mocked application tests
Robust integration tests

📊 Measurable Benefits

Test coverage:   30% → 85%
Deploy frequency: 1/week → 5/day
Defect rate:     15% → 2%

🚀 Migration Strategy

Extract domain
Isolate use cases
Implement adapters

✅ When to use Hexagonal Architecture

Complex enterprise systems
Long-term scalable applications
Teams prioritizing maintainability

❌ When to avoid

Quick MVPs
Simple CRUDs
Time-constrained prototypes

Hexagonal Architecture is not an end, but a means to create sustainable software systems that evolve without fear. Fewer dependencies, more control, and significantly fewer 3 AM production nightmares.