Best hexagonal course ever

Jose Manuel Castellano Jiménez — Mon, 25 Aug 2025 18:06:24 +0000

Excellent choice! This repository is a very well-structured **production architecture reference.

Suggested Study Plan

1. Start with the Documentation

docs/
├── learn_hexagonal/learn_hexagonal.md    # START HERE!
├── architecture/C4-containers.md         # High-level view
└── runbook.md                            # Operations

Why: The learn_hexagonal documentation will map out exactly how the concepts we discussed are implemented.

2. Analyze the Structure of ONE Service First

I recommend starting with user-service because it is the simplest:

services/user-service/
├── src/main/java/com/ecotrack/user/
│   ├── domain/          # ← CORE: Entities, Value Objects, Domain Services
│   ├── application/     # ← USE CASES: Application Services, Ports
│   ├── infrastructure/  # ← ADAPTERS: REST, JPA, Config
│   └── UserServiceApplication.java

3. Practical Hexagonal Mapping

Domain (Center of the Hexagon):

// services/user-service/src/main/java/com/ecotrack/user/domain/
├── User.java              # Main entity
├── UserRepository.java    # Port (interface) - NO implementation
├── Email.java             # Value Object
└── UserDomainService.java # Complex domain logic

Application (Use Cases):

// services/user-service/src/main/java/com/ecotrack/user/application/
├── CreateUserUseCase.java     # Use case
├── FindUserUseCase.java       # Another use case
└── ports/
    ├── in/                    # Input ports (what the domain exposes)
    └── out/                   # Output ports (what the domain needs)

Infrastructure (Adapters):

// services/user-service/src/main/java/com/ecotrack/user/infrastructure/
├── web/
│   └── UserController.java    # REST Adapter (IN Port)
├── persistence/
│   └── JpaUserRepository.java # JPA Adapter (OUT port)
└── config/
    └── BeanConfiguration.java # Dependency injection

4. Data Flow to Follow

HTTP Request → UserController (Adapter)
Controller → CreateUserUseCase (Application)
Use Case → UserDomainService (Domain)
Domain → UserRepository interface (Port)
Interface → JpaUserRepository (Adapter)
JPA → PostgreSQL

5. Key Concepts to Look For

Dependency Injection:

@Component
public class CreateUserUseCase {
    private final UserRepository userRepository; // Port, not implementation

    public CreateUserUseCase(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
}

Configuration (Composition Root):

@Configuration
public class BeanConfiguration {
    @Bean
    public UserRepository userRepository() {
        return new JpaUserRepository(); // Here the adapter connects to the port
    }
}

6. Compare with the CQRS Diagram

The project probably implements:

Commands: CreateUserUseCase, UpdateUserUseCase
Queries: FindUserUseCase, GetUserProfileUseCase
Events: See tracking-service using Kafka

7. Layered Learning Approach

Week 1: A single service (user-service)

Folder structure
HTTP flow → Domain → DB
Testing each layer

Week 2: Communication between services

tracking-service → Kafka → notification-service
Events and asynchronous messaging

Week 3: Infrastructure & DevOps

Docker Compose setup
Kubernetes manifests
Observability (metrics, logs)

8. Suggested Practical Exercises

Map the complete flow of creating a user
Add a new endpoint following the same pattern
Write tests for each layer separately
Modify the implementation of persistence (change from JPA to something else)

9. Questions to Ask Yourself

Where are the business rules?
How are dependencies injected?
What would happen if I replaced PostgreSQL with MongoDB?
How is each layer tested independently?
How do services communicate with each other?

10. Red Flags to Avoid

Don't copy code without understanding why it's there
Don't implement all services at once
Don't ignore tests—they reveal a lot about the architecture
Don't skip the learn_hexagonal documentation

Tip: After you understand a service well, try to recreate the structure from scratch with a different domain (e.g., a library, a simple e-commerce site). This will confirm that you really understood the patterns.

Which service would you like to start with? I strongly recommend user-service because it is the most straightforward for understanding the fundamentals.

Translated with DeepL.com (free version)

DEV Community: Jose Manuel Castellano Jiménez