DEV Community: rezahazegh

Hexagonal Architecture Demo - Task Management System

rezahazegh — Sun, 28 Dec 2025 14:26:09 +0000

A Spring Boot application demonstrating Hexagonal Architecture (also known as Ports and Adapters) with a Task Management system. This project showcases clean separation of concerns, dependency inversion, and testable code structure.

📄 Repository

https://github.com/rezahazegh/demo-hexagonal-architecture

📋 Table of Contents

Architecture Overview
What is Hexagonal Architecture?
Project Structure
Key Design Principles
Technologies Used
Getting Started
API Documentation
Testing
Benefits of This Architecture

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     Infrastructure Layer                      │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Inbound Adapters (Input)                │   │
│  │         REST API Controllers & DTOs                   │   │
│  └──────────────────┬───────────────────────────────────┘   │
│                     │                                         │
│  ┌─────────────────▼────────────────────────────────────┐   │
│  │              Application Layer                        │   │
│  │        Use Cases & Business Orchestration             │   │
│  └─────────────────┬────────────────────────────────────┘   │
│                     │                                         │
│  ┌─────────────────▼────────────────────────────────────┐   │
│  │                Domain Layer (Core)                    │   │
│  │        Business Logic & Domain Models                 │   │
│  │              No External Dependencies                 │   │
│  └─────────────────┬────────────────────────────────────┘   │
│                     │                                         │
│  ┌─────────────────▼────────────────────────────────────┐   │
│  │             Outbound Adapters (Output)                │   │
│  │      PostgreSQL Repository & Persistence              │   │
│  └───────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Layer Interaction Flow

REST Request → Controller → Application Service → Domain Logic → Repository → Database

The dependency rule: Dependencies point inward (Infrastructure → Application → Domain)

🎯 What is Hexagonal Architecture?

Hexagonal Architecture (coined by Alistair Cockburn) is a software design pattern that creates loosely coupled application components.

Core Concepts

Domain (Core/Hexagon): The business logic lives here, completely isolated from external concerns
- Pure business rules
- Domain models
- Domain exceptions
- No framework dependencies
Ports: Interfaces that define contracts
- Input Ports: Define use cases (e.g., TaskService)
- Output Ports: Define what the domain needs from external systems (e.g., TaskRepository)
Adapters: Implementations that connect to the outside world
- Inbound/Primary Adapters: Drive the application (e.g., REST controllers, CLI)
- Outbound/Secondary Adapters: Driven by the application (e.g., database repositories, external APIs)

Why "Hexagonal"?

The hexagon shape symbolizes that the architecture can have multiple adapters on each side - it's not limited to just one input or output method.

📁 Project Structure

dev.hazegh.demo_hexagonal_architecture/
│
├── domain/                                    # 🔵 CORE DOMAIN (No external dependencies)
│   ├── model/
│   │   ├── Task.java                         # Domain entity with business logic
│   │   └── TaskStatus.java                   # Enum (TODO, IN_PROGRESS, DONE)
│   ├── exception/
│   │   ├── TaskNotFoundException.java
│   │   └── InvalidTaskStateException.java
│   └── port/
│       └── output/
│           └── TaskRepository.java           # Output port interface
│
├── application/                               # 🟢 APPLICATION LAYER
│   ├── port/
│   │   └── input/
│   │       └── TaskService.java              # Input port (use case interface)
│   └── service/
│       └── TaskServiceImpl.java              # Use case implementation
│
└── infrastructure/                            # 🟠 INFRASTRUCTURE LAYER
    └── adapter/
        ├── input/
        │   └── rest/
        │       ├── TaskController.java       # REST API adapter
        │       ├── dto/
        │       │   ├── CreateTaskRequest.java
        │       │   ├── UpdateTaskRequest.java
        │       │   ├── ChangeStatusRequest.java
        │       │   └── TaskResponse.java
        │       └── exception/
        │           ├── GlobalExceptionHandler.java
        │           └── ErrorResponse.java
        └── output/
            └── persistence/
                ├── entity/
                │   └── TaskJpaEntity.java    # JPA entity (infrastructure concern)
                ├── mapper/
                │   └── TaskMapper.java       # Maps between domain and JPA
                ├── TaskJpaRepository.java    # Spring Data JPA interface
                └── TaskRepositoryAdapter.java # Implements domain port

🔑 Key Design Principles

1. Dependency Inversion Principle

High-level modules (domain) don't depend on low-level modules (infrastructure)
Both depend on abstractions (ports/interfaces)

2. Separation of Concerns

Domain: Business rules (e.g., "A completed task cannot go back to TODO")
Application: Orchestration (e.g., "Find task, change status, save task")
Infrastructure: Technical details (e.g., REST, JPA, PostgreSQL)

3. Testability

Domain logic can be tested without any frameworks
Application logic can be tested with mocked repositories
Each layer can be tested independently

4. Flexibility

Easy to swap adapters (e.g., PostgreSQL → MongoDB, REST → GraphQL)
Domain remains unchanged when infrastructure changes

🛠️ Technologies Used

Java 21
Spring Boot 4.0.1
- Spring Web (REST API)
- Spring Data JPA (Persistence)
- Spring Validation (Bean validation)
PostgreSQL (Production database)
H2 (Test database)
Lombok (Reduce boilerplate)
Maven (Build tool)
Docker & Docker Compose (Containerization)
JUnit 5 & Mockito (Testing)

🚀 Getting Started

Prerequisites

Java 21 or higher
Docker and Docker Compose
Maven 3.9+ (or use the included Maven wrapper)

1. Clone the Repository

git clone https://github.com/rezahazegh/demo-hexagonal-architecture
cd demo-hexagonal-architecture

2. Start PostgreSQL Database

docker-compose up -d

This will start PostgreSQL on localhost:5432 with:

Database: taskdb
Username: taskuser
Password: taskpass

3. Run the Application

Using Maven Wrapper (Recommended):

./mvnw spring-boot:run

Or using Maven:

mvn spring-boot:run

The application will start on http://localhost:8080

4. Verify the Application

curl http://localhost:8080/api/tasks

You should receive an empty array [] (no tasks yet).

📚 API Documentation

Base URL

http://localhost:8080/api/tasks

Endpoints

1. Create a Task

POST /api/tasks
Content-Type: application/json

{
  "title": "Learn Hexagonal Architecture",
  "description": "Study the concepts and implement a demo project"
}

Response: 201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Learn Hexagonal Architecture",
  "description": "Study the concepts and implement a demo project",
  "status": "TODO",
  "createdAt": "2025-12-26T10:00:00",
  "updatedAt": "2025-12-26T10:00:00"
}

2. Get All Tasks

GET /api/tasks

Response: 200 OK
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Learn Hexagonal Architecture",
    "description": "Study the concepts and implement a demo project",
    "status": "TODO",
    "createdAt": "2025-12-26T10:00:00",
    "updatedAt": "2025-12-26T10:00:00"
  }
]

3. Get Task by ID

GET /api/tasks/{id}

Response: 200 OK
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Learn Hexagonal Architecture",
  "description": "Study the concepts and implement a demo project",
  "status": "TODO",
  "createdAt": "2025-12-26T10:00:00",
  "updatedAt": "2025-12-26T10:00:00"
}

4. Update Task

PUT /api/tasks/{id}
Content-Type: application/json

{
  "title": "Master Hexagonal Architecture",
  "description": "Deep dive into advanced concepts"
}

Response: 200 OK

5. Change Task Status

PATCH /api/tasks/{id}/status
Content-Type: application/json

{
  "status": "IN_PROGRESS"
}

Response: 200 OK

Valid status transitions:

TODO → IN_PROGRESS ✅
TODO → DONE ✅
IN_PROGRESS → DONE ✅
DONE → TODO ❌ (Business rule violation)
DONE → IN_PROGRESS ❌ (Business rule violation)

6. Delete Task

DELETE /api/tasks/{id}

Response: 204 No Content

Error Responses

Validation Error

{
  "timestamp": "2025-12-26T10:00:00",
  "status": 400,
  "error": "Validation Failed",
  "message": "Invalid input data",
  "path": "/api/tasks",
  "validationErrors": [
    {
      "field": "title",
      "message": "Title is required"
    }
  ]
}

Not Found

{
  "timestamp": "2025-12-26T10:00:00",
  "status": 404,
  "error": "Not Found",
  "message": "Task not found with id: 550e8400-e29b-41d4-a716-446655440000",
  "path": "/api/tasks/550e8400-e29b-41d4-a716-446655440000"
}

Invalid State Transition

{
  "timestamp": "2025-12-26T10:00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Failed to change status: Cannot move a completed task back to TODO",
  "path": "/api/tasks/550e8400-e29b-41d4-a716-446655440000/status"
}

🧪 Testing

Run All Tests

./mvnw test

Test Structure

Unit Tests

Domain Tests (TaskTest.java): Test business logic in isolation
Application Tests (TaskServiceImplTest.java): Test use cases with mocked dependencies
Mapper Tests (TaskMapperTest.java): Test data transformations

Integration Tests

REST API Tests (TaskControllerIntegrationTest.java): End-to-end API testing
Repository Tests (TaskRepositoryAdapterTest.java): Database integration testing

Test Coverage

The tests demonstrate:

✅ Business rule enforcement (e.g., status transition rules)
✅ Validation handling
✅ Error scenarios (not found, invalid state)
✅ CRUD operations
✅ Mapper bidirectional conversions
✅ Repository persistence

💡 Benefits of This Architecture

1. Independence from Frameworks

The core business logic doesn't depend on Spring, JPA, or any framework
Frameworks become implementation details

2. Testability

Domain logic can be tested without any infrastructure
Easy to write unit tests with minimal setup
Clear boundaries make mocking straightforward

3. Flexibility

Database change: Swap PostgreSQL for MongoDB without touching domain/application
API change: Add GraphQL alongside REST without modifying business logic
Add new adapters: CLI, gRPC, message queue - all without changing the core

4. Maintainability

Clear separation makes code easier to understand
Changes in one layer don't ripple through the entire application
Each component has a single responsibility

5. Business Logic Protection

Domain rules are explicit and enforced in one place
No risk of bypassing business logic through different entry points

6. Team Scalability

Different teams can work on different layers independently
Clear contracts (ports) reduce integration conflicts

🔄 Example: Swapping Adapters

Current Setup

REST API (Inbound)
PostgreSQL (Outbound)

Adding a New Adapter (e.g., CLI)

You can add a CLI adapter without changing domain or application:

@Component
public class TaskCliAdapter implements CommandLineRunner {
    private final TaskService taskService;

    @Override
    public void run(String... args) {
        Task task = taskService.createTask("CLI Task", "Created from CLI");
        System.out.println("Created task: " + task.getId());
    }
}

Swapping Database (PostgreSQL → MongoDB)

Just create a new adapter implementing TaskRepository:

@Repository
public class MongoTaskRepository implements TaskRepository {
    private final MongoTemplate mongoTemplate;
    // Implementation using MongoDB
}

The domain and application layers remain unchanged!

🐳 Docker Commands

# Start PostgreSQL
docker-compose up -d

# Stop PostgreSQL
docker-compose down

# View logs
docker-compose logs -f postgres

# Clean up (removes volumes)
docker-compose down -v

📝 Environment Variables

Copy .env.example to .env and customize if needed:

cp .env.example .env

Default values:

POSTGRES_DB=taskdb
POSTGRES_USER=taskuser
POSTGRES_PASSWORD=taskpass
POSTGRES_PORT=5432

📖 Further Reading

Built with ❤️ to demonstrate Hexagonal Architecture principles

Understanding Object-Relational Impedance Mismatch

rezahazegh — Thu, 31 Oct 2024 09:38:27 +0000

Object-relational impedance mismatch refers to the challenges that arise when you try to bridge the differences between object-oriented programming languages (which use object models) and relational databases. Here’s a breakdown of why this happens:

Data Structure Mismatch:
- Object Model: Organizes data in objects and classes, using attributes and methods that represent real-world entities. Objects may contain nested objects, hierarchies, and complex relationships.
- Relational Database: Organizes data in tables with rows and columns, following strict schemas. Relationships between entities are represented through foreign keys and join tables.

This structural difference makes it difficult to directly map objects to tables.

Inheritance:
- Object Model: Allows for inheritance, meaning that a class can inherit properties and behavior from another class.
- Relational Database: Lacks a straightforward way to represent inheritance. This typically requires extra tables or additional columns in relational models to mimic inheritance, complicating data design and retrieval.
Identity and References:
- Object Model: Uses direct object references, meaning an object has a pointer to another object, forming a web of interconnected instances.
- Relational Database: Uses foreign keys and joins to establish relationships, which requires querying and joining tables to retrieve related data.
Data Retrieval:
- Object Model: Can directly access related objects (e.g., user.address.street).
- Relational Database: Requires SQL queries, often involving multiple joins, which can lead to complex query logic.
CRUD Operations:
- Object Model: Can be less predictable when saved to a relational database due to cascades of complex relationships and updates, making transactional control challenging.
- Relational Database: Designed to handle CRUD operations but with simpler data models. Object-oriented models need ORMs (Object-Relational Mappers) to translate objects to tables and vice versa.

Solutions to Impedance Mismatch

ORM (Object-Relational Mapping) frameworks like Hibernate (Java), SQLAlchemy (Python), and Entity Framework (.NET) help map objects to relational tables, providing an abstraction that simplifies CRUD operations.

Error handling in express.js

rezahazegh — Wed, 25 Oct 2023 17:31:31 +0000

Introduction

In this article, I used the code in the following repository:
https://github.com/rezahazegh/demo-express-error-handling

To demonstrate how express.js behaves regarding error handling by using some pretty straightforward examples. Then, I provided a solution to have cleaner syntax to handle errors.

Hint: express.js behavior is different for version 5 and above.

Trail and Error

The project includes some routes which show express behavior under different conditions:

/test
- We use it to check either app crashed or still working
/sync
- If you call this route it throws an error from within a sync route handler.
- if we call test the app would work. So, express catches it automatically and, we don't need any extra action for sync handlers.
/async-not-handled
- If you call this route it throws an error from within an async route handler which is not handled.
- If you call test the app won't work and, you will see it already crashed.
- So, we need to somehow handle errors for async handlers. we show how to do that on the next ones.
/async-handled-regular
- If you call this route it throws an error from within an async route handler which is handled using try/catch.
- The point is you should pass error to next function.
- Now, if we call test the app would work.

Magic solution

The following solution helps you to get rid of try/catch in your handlers.

Functions in javascript are first class citizens:

you can pass a function as a parameter to another one.
Also, you can return a function as a return value.

We are going to use these features to design our solution.

handler function helps us to extract try/catch from our handlers. It takes our handler as a parameter and wrap it in a try/catch in a new function. Then return the new function.

/async-handled-using-handler
- If you call this route it throws an error from within an async route handler which is handled using handler function.
- Now, if we call test the app would work.

GraphQL server demo via express and @apollo/server

rezahazegh — Wed, 18 Jan 2023 16:10:20 +0000

The following repository demonstrates a simple GraphQL server app via express and @apollo/server.
https://github.com/rezahazegh/demo-apollo-server

Project Description

This project contains Course and Teacher entities, It provides create, update and delete for them.

Entities relation: Every course would have a teacher.

Directory Description

models: It includes required mongoose models to store entities in MongoDB
schema: it include GraphQL related stuff
- types: It includes types, something like dto in REST API
- resolvers: It include resolvers, something like route handlers in REST API

Project Setup

Run docker compose up -d to setup MongoDB via docker

Run app and open localhost:4000 to reach out to Apollo Sandbox (An in-browser tool for writing, validating, and testing GraphQL queries)

Sample Requests

Create, Read and Delete Teacher

mutation {
  addTeacher(name: "Peter Parker", email: "spiderman@gmail.com", phone: "855-465-2386") {
    id
    name
    email
    phone
  }
}

{
  teachers {
    id,
    name
  }
}

{
  teacher(id: "63c421e024a2dcb1e5dcdce6") {
    id,
    name
  }
}

mutation {
  deleteTeacher(id: "63c421e024a2dcb1e5dcdce6") {
    id,
    name
  }
}

Create, Read, Update and Delete Course

mutation {
  addCourse(name: "GraphQL by Spider-Man", description: "This is the project description", status: new, teacherId: "63c424b724a2dcb1e5dcdcef") {
   name
   description
  }
}

{
  courses {
    id,
    name,
    status
  }
}

{
  course(id: "63c4252c24a2dcb1e5dcdcf1") {
    id,
    name,
    status
  }
}

mutation {
  updateCourse(id: "63c4252c24a2dcb1e5dcdcf1", status: completed) {
   name
   status
  }
}

mutation {
  deleteCourse(id: "63c4252c24a2dcb1e5dcdcf1") {
    id
  }
}

GraphQL server demo via express and express-graphql

rezahazegh — Sun, 15 Jan 2023 16:39:16 +0000

The following repository demonstrates a simple GraphQL server app via express and express-graphql.
https://github.com/rezahazegh/demo-express-graphql

Project Description

This project contains Course and Teacher entities, It provides create, update and delete for them.

Entities relation: Every course would have a teacher.

Directory Description

models: It includes required mongoose models to store entities in MongoDB
schema: it include GraphQL related stuff
- types: It includes types, something like dto in REST API
- resolvers: It include resolvers, something like route handlers in REST API

Project Setup

Run docker compose up -d to setup MongoDB via docker

Run app and open localhost:3000/graphql to reach out to GraphiQL (An in-browser tool for writing, validating, and testing GraphQL queries)

Sample Requests

Create, Read and Delete Teacher

mutation {
  addTeacher(name: "Peter Parker", email: "spiderman@gmail.com", phone: "855-465-2386") {
    id
    name
    email
    phone
  }
}

{
  teachers {
    id,
    name
  }
}

{
  teacher(id: "63c421e024a2dcb1e5dcdce6") {
    id,
    name
  }
}

mutation {
  deleteTeacher(id: "63c421e024a2dcb1e5dcdce6") {
    id,
    name
  }
}

Create, Read, Update and Delete Course

mutation {
  addCourse(name: "GraphQL by Spider-Man", description: "This is the project description", status: new, teacherId: "63c424b724a2dcb1e5dcdcef") {
   name
   description
  }
}

{
  courses {
    id,
    name,
    status
  }
}

{
  course(id: "63c4252c24a2dcb1e5dcdcf1") {
    id,
    name,
    status
  }
}

mutation {
  updateCourse(id: "63c4252c24a2dcb1e5dcdcf1", status: completed) {
   name
   status
  }
}

mutation {
  deleteCourse(id: "63c4252c24a2dcb1e5dcdcf1") {
    id
  }
}

Nest.js integration with Kafka

rezahazegh — Sun, 08 Jan 2023 17:38:02 +0000

The following repository demonstrates a simple microservice app which integrates NestJS with Apache Kafka.
https://github.com/rezahazegh/kafka-nestjs

Project Description

Producer receives two number via REST API.
Producer sends numbers to kafka sum topic.
Consumer subscribes to sum topic and receives numbers and returns sum of numbers.

Directory Description

infra directory includes docker-compose to setup kafka
producer directory includes a projects which send payloads to kafka
consumer directory includes a project which receives payloads from kafka

Run and Test

After setup kafka and running producer and consumer you can call localhost:3000 by POST method.

Sample Payload:

{
    "num1": 7,
    "num2": 9
}

Sample Response:

Sum of 7 and 9 is: 16

List of Kafka Topics

By running npm run topic-list inside infra directory, you can see list of kafka topics.

Sample Response:

__consumer_offsets
sum
sum.reply