🏗️ Hexagonal Architecture with Spring Boot

Personal exploration project to implement Hexagonal Architecture (Clean Architecture) alongside modern automation tools in the Spring Boot ecosystem.

📋 Table of Contents

• Description
• Architecture
• Tech Stack
• Project Structure
• Installation and Execution
• API Endpoints
• Technical Features
• Key Learnings

📖 Description

This project implements a product management system using Hexagonal Architecture, with the goal of exploring clean architecture patterns and code automation tools. The system exposes a complete REST API for CRUD operations on products.

Project Goals

• Implement Hexagonal Architecture with clear separation of concerns
• Automate API code generation using OpenAPI Generator
• Explore modern tools in the Spring Boot ecosystem
• Apply development and testing best practices

🏛️ Architecture

The project follows Hexagonal Architecture principles by organizing code into the following layers:

┌─────────────────────────────────────────┐
│            🌐 API Layer                 │
│        (Controllers, DTOs)              │
├─────────────────────────────────────────┤
│         🧠 Application Layer            │
│       (Services, Use Cases)            │
├─────────────────────────────────────────┤
│          💎 Domain Layer                │
│    (Entities, Business Rules)          │
├─────────────────────────────────────────┤
│       🔌 Infrastructure Layer          │
│    (Repositories, Database, JPA)       │
└─────────────────────────────────────────┘

Ports and Adapters

• Port: ProductRepository (domain interface)
• Adapter: ProductRepositoryAdapter (JPA implementation)

🛠️ Tech Stack

Technology	Version	Purpose
Java	17	Base language
Spring Boot	3.x	Main framework
Spring Data JPA	-	Data persistence
PostgreSQL	-	Database
OpenAPI Generator	-	Automatic API generation
MapStruct	-	Layer mapping
Lombok	-	Boilerplate reduction
Maven	-	Dependency management
Hibernate Validator	-	Data validation

📁 Project Structure

barcodehub/
├── domain/                     # 💎 Domain Layer
│   ├── src/main/java/
│   │   ├── model/
│   │   │   └── Product.java
│   │   └── exception/
│   │       ├── NotFoundException.java
│   │       └── BusinessErrorCodes.java
│   └── pom.xml
├── app-service/                # 🧠 Application Layer
│   ├── src/main/java/
│   │   ├── service/
│   │   ├── port/
│   │   │   └── ProductRepository.java
│   │   └── mapper/
│   │       └── ProductMapper.java
│   └── pom.xml
├── infrastructure/             # 🔌 Infrastructure Layer
│   ├── src/main/java/
│   │   ├── adapter/
│   │   │   └── ProductRepositoryAdapter.java
│   │   ├── entity/
│   │   │   └── ProductEntity.java
│   │   ├── repository/
│   │   │   └── JpaProductRepository.java
│   │   ├── controller/
│   │   │   └── ProductController.java
│   │   └── mapper/
│   │       └── ProductEntityMapper.java
│   ├── src/main/resources/
│   │   ├── openapi.yaml
│   │   └── application.properties
│   └── pom.xml
└── pom.xml                     # Parent POM

🚀 Installation and Execution

Prerequisites

• Java 17+
• Maven 3.8+
• PostgreSQL 12+

Installation Steps

1. Clone the repository

   git clone <repository-url>
   cd barcodehub

2. Setup database

   CREATE DATABASE productdb;

3. Configure properties (optional)

   # src/main/resources/application.properties
   spring.datasource.url=jdbc:postgresql://localhost:5432/productdb
   spring.datasource.username=your_user_postgre
   spring.datasource.password=your_password_postgre

4. Compile the project

   mvn clean compile

5. Run the application

   mvn spring-boot:run -pl infrastructure

The application will be available at http://localhost:8080

🌐 API Endpoints

Method	Endpoint	Description
GET	/products	Get all products
POST	/products	Create a new product
GET	/products/{id}	Get product by ID
PUT	/products/{id}	Update existing product
DELETE	/products/{id}	Delete product

Example Payload

{
  "name": "Dell XPS Laptop",
  "price": 1299.99
}

✨ Technical Features

🔄 Automatic Code Generation

• OpenAPI Generator automatically generates:
  • Controller interfaces (ProductApi)
  • API DTOs (ProductDto, DataProductListDto)
  • Validation annotations
  • API documentation

🗺️ Automatic Layer Mapping

• MapStruct handles mapping between:
  • Product (Domain) ↔ ProductEntity (JPA)
  • Product (Domain) ↔ ProductDto (API)

🧩 Multi-module Maven Configuration

• OpenAPI Generator Plugin: Compile-time generation
• Build Helper Plugin: Generated code integration
• Annotation Processing: Lombok + MapStruct

💡 Key Learnings

✅ Hexagonal Architecture

• Clear separation of responsibilities facilitates testing and maintenance
• Ports and adapters allow changing implementations without affecting domain
• Dependency inversion makes code more testable and flexible

✅ Code Automation

• OpenAPI Generator significantly reduces boilerplate code
• YAML specifications as single source of truth for API
• Build-time generation keeps code and documentation synchronized

✅ Spring Ecosystem Tools

• Spring Data JPA simplifies persistence operations
• MapStruct is incredibly efficient for object mapping
• Maven multi-module better organizes complex projects

✅ Best Practices

• Domain validation keeps business rules centralized
• Custom exceptions improve error handling
• Layer-specific DTOs avoid coupling

🤝 Contributing

This is a personal learning project, but if you find improvements or have suggestions, feel free to:

1. Fork the project
2. Create a feature branch (git checkout -b feature/improvement)
3. Commit your changes (git commit -am 'Add new improvement')
4. Push to the branch (git push origin feature/improvement)
5. Create a Pull Request

---

⭐ If you found this project useful, don't forget to give it a star

📬 Have questions? Feel free to open an issue or contact me directly.

---

Developed with ❤️ to explore modern architectures and development best practices