DEV Community: Francesco Portus

SmartOrder — Part 5: The Commons Layer — Shared Infrastructure Done Right

Francesco Portus — Mon, 16 Mar 2026 16:58:08 +0000

How a carefully designed shared library eliminates boilerplate across microservices — generics, AOP logging, custom Jackson modules, and a test framework you'll wish you had years ago.

Part 4 explored the Inventory Service. Before moving forward, there's a layer that quietly powers everything — a layer most tutorials skip entirely. This post dives into services/commons: the shared infrastructure that both order-service and inventory-service depend on.

Commons is not a dumping ground. It's a deliberate, multi-module library that solves real problems: generic CRUD, consistent serialization, AOP-based observability, OpenAPI cleanup, and test data lifecycle management. Let's take it apart.

👉 services/commons

The three sub-modules at a glance

services/commons
├── commons-business   ← domain-layer abstractions (no web dependency)
├── commons-service    ← web-layer infrastructure (HATEOAS, Jackson, AOP)
└── service-test       ← test utilities with transaction control

The split is intentional. commons-business has no Spring MVC dependency — it can be pulled into any service without dragging in a web container. commons-service assumes a web context and brings in HATEOAS, OpenAPI, and AOP support.

commons-business: Generic CRUD without the ceremony

The Entity contract

Every domain object in SmartOrder implements a single interface:

public interface Entity<I> {
  I getId();
  void setId(I id);
}

Simple. But it's the foundation for the entire generic CRUD stack. Inventory uses UUID, Order uses ObjectId — the abstraction doesn't care.

AbstractCrudService: one class to rule them all

public abstract class AbstractCrudService<T extends Entity<I>, I, R extends CrudRepository<T, I>>
    implements CrudService<T, I> {

  protected final R repository;

  @Override
  public <S extends T> Optional<S> update(I id, S entity) {
    return findById(id)
        .map(existing -> {
          BeanUtils.copyProperties(entity, existing, ServiceUtils.getImmutableFields(existing));
          return (S) save(existing);
        });
  }
}

The update method is the interesting part. It uses BeanUtils.copyProperties but excludes immutable fields automatically. No manually listing "id", "createdDate", "lastModifiedDate" in every service.

ServiceUtils: reflection-based field protection

public static <S extends Entity<?>> String[] getImmutableFields(S entity) {
  Set<String> ignored = new HashSet<>();
  ignored.add("id");

  ignored.addAll(
      Arrays.stream(entity.getClass().getDeclaredFields())
          .filter(ServiceUtils::isAuditingField)
          .map(Field::getName)
          .toList());

  return ignored.toArray(new String[0]);
}

private static boolean isAuditingField(Field field) {
  return field.isAnnotationPresent(CreatedDate.class)
      || field.isAnnotationPresent(LastModifiedDate.class);
}

Any field annotated with @CreatedDate or @LastModifiedDate is automatically excluded from updates. This convention-over-configuration approach means services never accidentally overwrite audit timestamps — and it works without touching a single business class.

JPA vs Mongo — two concrete services, zero duplication

// For JPA (Inventory Service)
public abstract class JpaCrudService<T extends Entity<I>, I>
    extends AbstractCrudService<T, I, JpaRepository<T, I>> {

  @Override
  public Page<T> findAll(Pageable pageable) {
    return repository.findAll(pageable);
  }
}

// For MongoDB (Order Service)
public abstract class MongoCrudService<T extends Entity<I>, I>
    extends AbstractCrudService<T, I, MongoRepository<T, I>> {

  @Override
  public Page<T> findAll(Pageable pageable) {
    return repository.findAll(pageable);
  }
}

InventoryServiceImpl extends JpaCrudService and OrderServiceImpl extends MongoCrudService. Polyglot persistence — one generic layer.

commons-service: Where the real magic lives

Custom Jackson deserializers for Spring types

This is one of the most underrated pieces of the codebase. Spring's Page<T>, Pageable, PagedModel<T>, and EntityModel<T> don't serialize/deserialize symmetrically out of the box. Commons solves this with a set of custom Jackson modules that auto-register via JacksonAutoConfiguration.

The module architecture is elegant:

public class AbstractDeserializerModule<T> extends SimpleModule {

  private final Class<? super T> rawType;
  private final Function<JavaType, JsonDeserializer<? extends T>> deserializerFactory;

  @Override
  public void setupModule(SetupContext context) {
    super.setupModule(context);
    context.addDeserializers(new Deserializers.Base() {
      @Override
      public JsonDeserializer<?> findBeanDeserializer(
          JavaType javaType, DeserializationConfig config, BeanDescription beanDesc) {
        if (rawType.equals(javaType.getRawClass())) {
          return deserializerFactory.apply(javaType);
        }
        return null;
      }
    });
  }
}

Each module is just a one-liner that extends this base:

public class PageModule extends AbstractDeserializerModule<Page<?>> {
  public PageModule() {
    super(Page.class, javaType -> new PageDeserializer<>(javaType.containedTypeOrUnknown(0)));
  }
}

PageDeserializer handles missing fields gracefully — no content array? Returns an empty list. No pageable? Returns Pageable.unpaged(). No totalElements? Falls back to content size.

@Override
public Page<T> deserialize(JsonParser parser, DeserializationContext ctxt) throws IOException {
  ObjectNode node = parser.readValueAsTree();

  List<T> content = extractContent(node, ctxt);
  Pageable pageable = extractPageable(node, ctxt);
  long totalElements = extractTotalElements(node, content);

  return new PageImpl<>(content, pageable, totalElements);
}

The same pattern applies to PagedModel, EntityModel, and Pageable. Any service that pulls commons-service gets symmetric serialization for free.

AOP logging with zero configuration

LoggingAspect intercepts every method in your business packages and logs start, result, duration, and errors — with a correlation ID automatically managed via MDC.

@Around("execution(* it.portus..*(..))" + " && !within(it.portus.ms.commons..*)")
public Object logMethod(ProceedingJoinPoint joinPoint) throws Throwable {
  // ...
  String correlationId = getOrGenerateCorrelationId();
  long start = System.currentTimeMillis();

  if (targetLogger.isDebugEnabled()) {
    targetLogger.debug("[correlationId: {}] {} - START with args: {}",
        correlationId, methodName, formatArgs(joinPoint.getArgs()));
  }

  try {
    Object result = joinPoint.proceed();
    long duration = System.currentTimeMillis() - start;
    targetLogger.info("[correlationId: {}] {} - SUCCESS in {} ms, result: {}",
        correlationId, methodName, duration, result);
    return result;
  } catch (Exception ex) {
    targetLogger.error("[correlationId: {}] {} - ERROR in {} ms: {}",
        correlationId, methodName, duration, ex.getMessage(), ex);
    throw ex;
  } finally {
    MDC.remove(CORRELATION_ID);
  }
}

The configuration is smart: it scans for @SpringBootApplication and @ComponentScan packages at startup, excluding the commons package itself. You can also extend it:

logging:
  aspect:
    extra-packages:
      - com.mycompany.special

No @EnableAspectJAutoProxy annotation required. No bean declaration. Just add commons-service and your methods are observed.

HATEOAS: pluralizing link relations

A subtle but important detail. Spring HATEOAS by default uses class names for link relations. Commons registers a custom PluralizingRelProvider that makes collection links grammatically correct:

@Override
public LinkRelation getCollectionResourceRelFor(Class<?> type) {
  return LinkRelation.of(English.plural(type.getSimpleName().toLowerCase()));
}

Inventory → "inventory" for item, "inventories" for collection. Order → "order" / "orders". Uses the evo-inflector library to handle English plural rules (company → companies, box → boxes).

HATEOASLinkUtils: resolving placeholder base paths

When services run behind a gateway, their self-links need to reflect the forwarded prefix — not the internal path. HATEOASLinkUtils handles this transparently by reading ${property.name:/default} placeholders from @RequestMapping annotations:

// Controller mapping:
@RequestMapping("${openapi.order-service.base-path:/api/v1}")

// At runtime, HATEOASLinkUtils resolves the placeholder from environment or ForwardedHeader:
public static Link buildLink(Class<?> controllerClazz, Environment env, Link rawLink) {
  return applyPlaceholder(controllerClazz, env, rawLink);
}

The same helper resolves affordances — so HAL-Forms metadata also gets correctly rewritten when accessed through the gateway. Clients never see internal URLs.

OpenAPI schema cleanup

Both services generate OpenAPI specs from code. Without intervention, Spring adds internal Spring types (RepresentationModel, Links, Link, PagedModel, etc.) to the schema — cluttering the API docs.

DefaultSchemaProcessorImpl solves this with a post-processing pipeline:

Replace certain schemas with custom definitions (e.g., PageMetadata gets a cleaner DTO)
Reorder schemas — business schemas first, utility schemas last
Inline internal schemas (like Links) wherever they're referenced
Remove internal schemas from the final components section

HateoasProcessorImpl extends this to handle HATEOAS-specific types and generates a correct Links schema as additionalProperties: { $ref: Link }.

@Override
protected <T> Optional<Schema<T>> resolveSchemaFromClass(Class<?> clazz) {
  if (Links.class.equals(clazz)) {
    Schema linkSchema = resolved.referencedSchemas.get("Link");
    ObjectSchema linksSchema = new ObjectSchema();
    linksSchema.additionalProperties(linkSchema);
    linksSchema.setDescription("HATEOAS Links");
    return Optional.of(linksSchema);
  }
  return super.resolveSchemaFromClass(clazz);
}

service-test: A test framework in 3 files

Most test frameworks force you to choose between loading all test data upfront or managing state manually. service-test introduces a cleaner model with @WithTestData.

The annotation

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface WithTestData {
  Class<? extends TestDataLoader>[] value();
  boolean transactional() default true;
  boolean rollback() default true;
}

You provide a TestDataLoader implementation:

@TestComponent
@RequiredArgsConstructor
public class InventoryTestDataLoader implements TestDataLoader {

  private final InventoryRepository inventoryRepository;

  @Override
  public void load() {
    inventoryRepository.saveAll(
        Instancio.ofList(Inventory.class)
            .size(5)
            .ignore(Select.field(Inventory::getId))
            .ignore(Select.field(Inventory::getCreatedDate))
            .ignore(Select.field(Inventory::getLastModifiedDate))
            .create());
  }
}

And annotate your test:

@DataJpaTest
@WithTestData(InventoryTestDataLoader.class)
@ImportAutoConfiguration(JpaAutoConfiguration.class)
@Import({InventoryServiceImpl.class})
class InventoryServiceTest {
  // each test runs with 5 random inventories pre-loaded
  // automatically rolled back after each test
}

How it works: WithTestDataListener

WithTestDataListener is registered as a TestExecutionListener via spring.factories. It hooks into beforeTestMethod and afterTestMethod:

If transactional = true (default): loads data within the existing test transaction — Spring rolls it back automatically
If transactional = false: opens a new PROPAGATION_REQUIRES_NEW transaction, commits or rolls back after the test based on the rollback flag

@Override
public void beforeTestMethod(TestContext testContext) {
  findAnnotation(testContext).ifPresent(annotation -> {
    Runnable loadData = () -> loadTestData(ctx, annotation);
    if (annotation.transactional()) {
      loadData.run();
      return;
    }
    // Start a new transaction for non-transactional tests
    TransactionStatus status = txManager.getTransaction(def);
    testContext.setAttribute(TX_STATUS_KEY, status);
    loadData.run();
  });
}

This gives you full control over test data lifecycle without reaching for @Sql scripts or Liquibase migrations in tests.

Auto-configuration: zero-config by design

All commons configuration registers itself via Spring Boot's AutoConfiguration.imports:

it.portus.ms.commons.config.CommonsAutoConfiguration
it.portus.ms.commons.config.HateoasConfiguration
it.portus.ms.commons.config.JacksonAutoConfiguration
it.portus.ms.commons.config.LoggingAspectAutoConfiguration
it.portus.ms.commons.config.MongoMappersConfiguration
it.portus.ms.commons.config.OpenApiCustomizerConfiguration

Every configuration class uses @ConditionalOnClass guards:

HateoasConfiguration only activates if HateoasConfiguration (Spring HATEOAS) is on the classpath
MongoMappersConfiguration only activates if ObjectId (MongoDB) is present
LoggingAspectAutoConfiguration only activates if AspectJ is present

This means services only pay for what they use. The Inventory Service doesn't get Mongo mappers. The gateway doesn't get JPA auditing utilities.

What makes this commons layer unusual

Most "commons" in enterprise codebases accumulate over years and become a mess of utilities nobody owns. SmartOrder's commons avoids this with three rules:

No circular dependencies — commons-business knows nothing about commons-service
Conditional everything — configs guard themselves with @ConditionalOnClass
Convention over configuration — auditing exclusions, package scanning, and pluralization are automatic

The result: onboarding a new service means adding one Maven dependency. CRUD, HATEOAS, logging, OpenAPI cleanup, and test data management come along for free.

What's next

With commons fully unpacked, the complete picture of SmartOrder's service architecture is clear. The next article will zoom out and look at the commons-service OpenAPI template customization — how Mustache templates are layered and overridden to produce clean, HATEOAS-aware generated code across both services.

Repo: → github.com/portus84/smartorder-ms

SmartOrder — Part 4: Inside the Inventory Service

Francesco Portus — Mon, 09 Mar 2026 09:54:23 +0000

Event-driven stock management, HATEOAS, and handling complex inventory logic across microservices.

Part 3 followed an order from HTTP request to RabbitMQ message. The OrderCreated event was left in the queue. This post focuses on how the Inventory Service consumes it, solves complex stock management challenges, and leverages shared commons infrastructure.

The Inventory Service is a major bounded context in SmartOrder. Structurally similar to Order Service — three-module Maven layout, contract-first API, HATEOAS responses — it introduces several patterns to solve enterprise challenges: polyglot persistence, eventual consistency, and reliable event-driven workflows.

👉 services/inventory-service

Ownership and boundaries

Inventory Service owns the stock state for each item — available, reserved, out of stock, discontinued. It does not manage order lifecycle or pricing. Boundaries are strict:

No cross-service joins
No shared schemas
No synchronous calls

It consumes OrderCreated events and reacts, enabling decoupled, eventually consistent microservices — a cornerstone of SmartOrder architecture.

The domain model and commons integration

@Entity
@Table
@Data
@Builder(toBuilder = true)
@NoArgsConstructor
@AllArgsConstructor
@Jacksonized
@EntityListeners(AuditingEntityListener.class)
public class Inventory implements it.portus.business.commons.model.Entity<UUID> {

  @Id
  @GeneratedValue(strategy = GenerationType.UUID)
  private UUID id;

  private String description;

  @NotNull
  @Builder.Default
  @Enumerated(EnumType.STRING)
  private InventoryStatus status = InventoryStatus.PENDING;

  @CreatedDate
  @Setter(AccessLevel.NONE)
  @Column(nullable = false, updatable = false)
  private LocalDateTime createdDate;

  @LastModifiedDate
  @Setter(AccessLevel.NONE)
  @Column(nullable = false)
  private LocalDateTime lastModifiedDate;
}

InventoryStatus drives the saga.
@CreatedDate/@LastModifiedDate leverage commons-business auditing.
Repository is intentionally thin:

public interface InventoryRepository extends JpaRepository<Inventory, UUID> {}

Polyglot persistence

Inventory Service uses Spring Data JPA with H2/Postgres, while Order Service uses MongoDB. Why?

Stock levels need atomic updates
Reservations require transactional semantics
JPA auditing simplifies commons integration

Commons modules provide base entities, mapper interfaces, and helpers, ensuring consistent patterns across services.

Event-driven consumption

@Bean
public Consumer<OrderCreatedEvent> orderCreatedConsumer() {
    return event -> orderConfirmationPublisher.send(event);
}

spring:
  cloud:
    function:
      definition: orderCreatedConsumer
    stream:
      function:
        bindings:
          orderCreatedConsumer-in-0: consumeOrderCreated
      bindings:
        consumeOrderCreated:
          destination: pending-orders
          group: inventory-group

inventory-group ensures single processing per event across instances
Stateless consumer, purely event-driven
Commons provide shared DTOs and binding constants:

@UtilityClass
public class BindingNames {
  public static final String PUBLISH_ORDER_CONFIRMED = "publishOrderConfirmed";
  public static final String PUBLISH_ORDER_OUT_OF_STOCK = "publishOrderOutOfStock";
}

Availability check and conditional event publishing

@Slf4j
@Component
@RequiredArgsConstructor
public class OrderConfirmationPublisher {

  private final StreamBridge streamBridge;
  private final InventoryService inventoryService;

  public void send(OrderCreatedEvent event) {
    boolean available = inventoryService.checkAvailability(event.getOrderId());
    if (available) {
      streamBridge.send(BindingNames.PUBLISH_ORDER_CONFIRMED, new OrderConfirmedEvent(event.getOrderId()));
    } else {
      streamBridge.send(BindingNames.PUBLISH_ORDER_OUT_OF_STOCK,
                        new OrderOutOfStockEvent(event.getOrderId(), "Insufficient stock"));
    }
  }
}

Decision logic is imperative but fully decoupled via events
Shared events-model from commons ensures consistent serialization
StreamBridge allows dynamic selection of output bindings

HATEOAS in REST responses

@Override
public ResponseEntity<EntityModel<Inventory>> getInventoryById(UUID id) {
    return inventoryService.findById(id)
        .map(inventoryMapper::toDTO)
        .map(hateoasHelper::toEntityModel)
        .map(ResponseEntity::ok)
        .orElseThrow(() -> new InventoryNotFoundException(id));
}

HATEOAS links generated via hateoasHelper guide clients dynamically
Supports patch/update operations without hardcoding URIs
Commons provide shared mapper interfaces, page mappers, HATEOAS helpers

Event-driven workflow: solved challenges

Order Service publishes OrderCreated
Inventory Service consumes it
OrderConfirmationPublisher decides based on stock
Events published: OrderConfirmedEvent or OrderOutOfStockEvent
Order Service updates state

Solved challenges:

Event-driven stock reservation without distributed transactions
Atomic availability checks leveraging JPA transactions
Shared infrastructure reduces boilerplate

TODO: `checkAvailability`

@Override
public boolean checkAvailability(String orderId) {
    // TODO: validate each product item against actual stock
    return true;
}

Placeholder always returns true
Next step for developers: integrate product line items from OrderCreatedEvent and validate quantities per stock record
This TODO is not part of this article's scope, but essential for full inventory correctness

Bootstrap and test data (developer hint)

@AutoConfiguration
@ConditionalOnClass(Instancio.class)
public class TestDataLoaderConfiguration {
  @Bean
  CommandLineRunner loadTestData(InventoryService service) {
    return args -> service.saveAll(Instancio.ofList(Inventory.class).size(5).ignoreFields().create());
  }
}

Instancio generates seed data for local development
Ensures consistent setup without touching production

What's next: commons modules

Focus will be on services/commons:

Shared business logic, DTOs, event definitions, and helpers
Sub-modules used across order-service and inventory-service
Includes:
- Entity base classes
- MapStruct mappers
- HATEOAS helpers
- Test data loaders

Commons are key to scaling SmartOrder without duplicating boilerplate.

Repo is open: → github.com/portus84/smartorder-ms

SmartOrder — Part 3: Inside the Order Service

Francesco Portus — Tue, 03 Mar 2026 10:21:25 +0000

From OpenAPI contract to domain event — a hands-on walkthrough of one bounded context, end to end.

If you've followed the series so far, you know the big picture: a multi-module Maven monorepo, a services layer that enforces DDD boundaries, an observability stack that boots with a single command. Good. Now let's open the hood.

This post focuses on the Order Service — the most central bounded context in SmartOrder. We'll trace a single request from the moment it hits the API contract all the way to the RabbitMQ event on the other side, looking at the real code along the way.

👉 services/order-service

What does the Order Service actually own?

Before writing a single line of code, it's worth asking: what does this service know, and what is explicitly none of its business?

The Order Service owns:

the lifecycle of an order (created → confirmed → shipped → delivered, or cancelled)
the order's line items and quantities
its own MongoDB collection

It does not own:

product details (that's the Product Service)
stock levels (that's Inventory)
pricing rules (at least not yet — fun contribution opportunity 👀)

This hard boundary is not just a design choice. It's enforced structurally. There's no cross-service database join, no shared schema, no sneaky @FeignClient call to fetch product names inside a transaction. If another service's data is needed, you go through its API or you listen to its events. Period.

The module structure: three modules, three responsibilities

The Order Service is itself a multi-module Maven project:

order-service/
├── api/        ← OpenAPI contract, generated interfaces, DelegateImpl, HATEOAS helpers
├── bootstrap/  ← test data initialization
├── business/   ← domain model, Drools rules, application layer, infrastructure adapters
└── pom.xml

This split is deliberate.

api is the public face of the service. It contains the OpenAPI spec, the Mustache-generated interfaces, the OrdersApiDelegateImpl that bridges the HTTP layer to the application layer, and the HATEOAS helper classes. Nothing in here knows about MongoDB or RabbitMQ. If the contract changes, this is the only module that needs to recompile — and the rest of the codebase fails at the right place, at the right time.

bootstrap handles test data initialization. When the full stack boots locally, you don't want to hit an empty database on every demo or integration test run. The bootstrap module seeds the MongoDB collection with a coherent initial dataset, so the service is immediately usable and the Grafana dashboards have something meaningful to display. Keeping it in its own module means that concern never leaks into production logic — no if (isDev) scattered around the codebase. It can be excluded from production builds entirely.

business is where the actual work happens. Domain model, application-layer use cases, infrastructure adapters (MongoDB repositories, RabbitMQ via Spring Cloud Stream), and — the part worth talking about at length — the Drools rule engine integration.

The separation between api and business means you can evolve the HTTP contract and the domain logic independently. Small monorepo trick, big dividend when the project grows.

Business rules with Drools: the state machine lives in `.drl` files

Most Spring Boot services handle business rules the obvious way: a chain of if statements in a service class. That works until the rules multiply, start interacting with each other, or need to change without touching Java code.

SmartOrder takes a different approach in the business module. Business rules — including the order state machine — are expressed as Drools .drl files. Here's the rule that seeds the working memory with valid state transitions:

rule "Initialize valid transitions"
    salience 100
    ruleflow-group "validation"
    when
        // always fires — seeds the working memory with valid transitions
    then
        // PENDING → PENDING / CONFIRMED / CANCELLED / OUT_OF_STOCK
        insert(new ValidTransition(OrderStatus.PENDING, OrderStatus.PENDING));
        insert(new ValidTransition(OrderStatus.PENDING, OrderStatus.CONFIRMED));
        insert(new ValidTransition(OrderStatus.PENDING, OrderStatus.CANCELLED));
        insert(new ValidTransition(OrderStatus.PENDING, OrderStatus.OUT_OF_STOCK));

        // CONFIRMED → CONFIRMED / SHIPPED / CANCELLED
        insert(new ValidTransition(OrderStatus.CONFIRMED, OrderStatus.CONFIRMED));
        insert(new ValidTransition(OrderStatus.CONFIRMED, OrderStatus.SHIPPED));
        insert(new ValidTransition(OrderStatus.CONFIRMED, OrderStatus.CANCELLED));

        // SHIPPED → SHIPPED / DELIVERED
        insert(new ValidTransition(OrderStatus.SHIPPED, OrderStatus.SHIPPED));
        insert(new ValidTransition(OrderStatus.SHIPPED, OrderStatus.DELIVERED));
end

query "validTransitionsFor" ( OrderStatus $from )
    ValidTransition( current == $from, $vt := this )
end

The .drl is the single source of truth for the state machine. There's no switch statement, no EnumSet somewhere else that could drift out of sync. When a new business requirement arrives — say, an ON_HOLD state — you change the rule file, and every part of the system that queries valid transitions picks it up automatically.

The Drools query at the bottom is also notable: it lets the application layer ask "what transitions are valid from this state?" and get back a list driven by the same rules, not by a hardcoded enum.

The rule engine: Strategy pattern over raw sessions

The integration on the Spring side is where it gets interesting. Rather than exposing KieSession directly, the engine uses the Strategy pattern to encapsulate each use case:

@Slf4j
@Service
@RequiredArgsConstructor
public class OrderRuleEngineImpl implements OrderRuleEngine {

    private final KieBase orderKieBase;

    @Override
    public Order applyRules(Order order) {
        return executeWithStrategy(order, new SimpleProcessingStrategy());
    }

    @Override
    public Order applyStatusTransition(Order order, OrderStatus newStatus) {
        return executeWithStrategy(order, new StatusTransitionStrategy(newStatus));
    }

    @Override
    public List<OrderStatus> getTransitionStatuses(Order order) {
        try (KieSession session = orderKieBase.newKieSession()) {
            return new TransitionStrategy().execute(session, order);
        }
    }

    private Order executeWithStrategy(Order order, OrderRuleStrategy strategy) {
        try (KieSession session = orderKieBase.newKieSession()) {
            return strategy.execute(session, order);
        }
    }
}

A few things worth noting here. KieBase — not KieContainer — is injected as a singleton: it holds the compiled rules and is thread-safe by design. KieSession is created fresh per execution and closed immediately with try-with-resources. Forgetting to close a KieSession is a common source of memory leaks in Drools applications; the try-with-resources makes it impossible to forget.

Each use case (applyRules, applyStatusTransition, getTransitionStatuses) gets its own strategy class. Adding a new rule use case means adding a new strategy — the engine itself doesn't change.

Contract-first: two YAML files, two roles

The api module exists before any controller. Two distinct YAML files drive the whole thing, and understanding their roles is important.

config.spring.api-v1.yml is the generator configuration — not the spec itself. It's the instruction set for the openapi-generator-maven-plugin: which Spring features to activate, where to find the spec, which Mustache templates to use. Think of it as the build-time manifest.

👉 config.spring.api-v1.yml

api-v1.yml is the actual OpenAPI specification. It lives under static/ so it's served at runtime — point Swagger UI or any OpenAPI tool at the running service and you get the live spec. Here's the relevant excerpt for the orders endpoints:

paths:
  /orders:
    post:
      operationId: addOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: "Created"
          x-hateoas: true
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Order'
    get:
      operationId: getOrders
      responses:
        '200':
          description: "Success"
          x-spring-page-type: it.portus.smartorder.ms.orderservice.api.v1.openapi.model.Order
          x-hateoas: true
          content:
            application/prs.hal-forms+json:
              schema:
                $ref: '#/components/schemas/PageOrder'

👉 api-v1.yml

Two things stand out. The POST returns application/hal+json — standard HATEOAS. The GET returns application/prs.hal-forms+json — HAL-FORMS, which also includes affordances describing what actions are available. And those x-hateoas and x-spring-page-type vendor extensions are not standard OpenAPI; they're the hook for the custom code generation described next.

Where the standard generator falls short: custom extensions + Mustache templates

Anyone who has tried to combine openapi-generator, Spring HATEOAS and pagination will have hit the same wall: the standard plugin has no concept of PagedModel<EntityModel<T>>. Out of the box it generates List<Order>, which is useless for a HATEOAS-first API.

SmartOrder solves this with two things working together.

Custom vendor extensions in the spec — x-hateoas: true flags an endpoint as needing HATEOAS wrapping. x-spring-page-type carries the fully-qualified entity class name for paginated responses. The generator ignores these (they're not in the spec), but custom Mustache templates can read them.

Custom Mustache templates in commons-service — the generator config points to a shared template directory:

services/commons/commons-service/src/main/resources/openapi/templates/

👉 templates/

These override the default generator output. When a template encounters x-hateoas: true, it emits the correct Spring HATEOAS return type. The result, instead of ResponseEntity<List<Order>>, is:

ResponseEntity<PagedModel<EntityModel<Order>>>

That's the exact signature in OrdersApiDelegateImpl:

@Component
public class OrdersApiDelegateImpl implements OrdersApiDelegate {

    @Override
    public ResponseEntity<PagedModel<EntityModel<Order>>> getOrders(
            Integer page, Integer size, List<String> sort, @Nullable OrderStatus status) {
        // application layer call → page of orders → assembled into PagedModel
    }
}

👉 OrdersApiDelegateImpl.java

The templates live in commons-service so every other service in the platform reuses the same generation logic. Add x-hateoas: true to a new endpoint anywhere in the repo and the right code comes out automatically, with no per-service configuration.

HATEOAS with affordances: more than just links

The GET /orders endpoint returns application/prs.hal-forms+json. That's not a typo — it's HAL-FORMS, which goes one step further than plain HATEOAS links by also including affordances: machine-readable descriptions of available actions (DELETE, PUT) with their expected payloads.

Look at HateoasOrderHelper:

public EntityModel<Order> toEntityModel(Order entity) {
    Link self = buildSelfLink(entity);

    return EntityModel.of(
        entity,
        HATEOASLinkUtils.buildLinks(
            CONTROLLER_CLAZZ,
            environment,
            self.andAffordance(
                    afford(WebMvcLinkBuilder.afford(
                        methodOn(CONTROLLER_CLAZZ).deleteOrder(entity.getId()))))
                .andAffordance(
                    afford(WebMvcLinkBuilder.afford(
                        methodOn(CONTROLLER_CLAZZ).updateOrder(entity.getId(), null))))
                .andAffordances(buildUpdateAffordances(self))));
}

👉 HateoasOrderHelper.java

A HAL-FORMS client receiving this response knows not just where the resource is, but also that it can be deleted and updated, and what shape those requests should take. The client doesn't need out-of-band documentation to discover this — it's in the response. This is relatively rare to see implemented correctly in a public reference project.

The valid state transitions are also built into the links dynamically, sourced from the Drools engine via getTransitionStatuses. The link set changes as the order moves through its lifecycle, driven by the same rules that govern transitions.

The domain event: outbox pattern, not wishful thinking

Once an order is validated by Drools and persisted, the service needs to notify the rest of the platform. The naive approach — persist to MongoDB, then publish to RabbitMQ — has a well-known flaw: if the publish fails after a successful write, you have an order with no event. The system is inconsistent.

SmartOrder solves this with a proper transactional outbox pattern. The event is first saved to MongoDB as an OrderOutboxEvent record, then sent asynchronously via OutboxSender:

@Slf4j
@Component
@RequiredArgsConstructor
public class OutboxSender {

    private final OrderOutboxRepository outboxRepository;
    private final StreamBridge streamBridge;
    private final ObjectMapper objectMapper;

    private final ExecutorService executor = Executors.newFixedThreadPool(5);

    public void sendAsync(OrderOutboxEvent outboxEvent) {
        CompletableFuture.runAsync(() -> send(outboxEvent), executor);
    }

    private void send(OrderOutboxEvent event) {
        try {
            Class<?> eventClass = Class.forName(event.getEventType());
            Object eventPayload = objectMapper.readValue(event.getPayload(), eventClass);

            boolean sent = streamBridge.send(BindingNames.PUBLISH_ORDER_CREATED, eventPayload);

            event.setStatus(sent ? EventStatus.SENT : EventStatus.FAILED);
            outboxRepository.save(event);
        } catch (Exception e) {
            log.error("Error sending outbox event {}", event.getId(), e);
            event.setStatus(EventStatus.FAILED);
            outboxRepository.save(event);
        }
    }
}

If the send fails, the event stays in MongoDB with FAILED status and can be retried. The outbox record is the durable guarantee — the message broker is best-effort on top of it.

The events themselves use the CloudEvents standard (contentType: application/cloudevents+json), which means they're interoperable with any broker or consumer that supports the spec, not tied to RabbitMQ specifics.

# async-api.yml (excerpt)
channels:
  orderEventsChannel:
    address: pending-orders
    messages:
      OrderCreatedMessage:
        $ref: '#/components/messages/OrderCreatedMessage'

components:
  messages:
    OrderCreatedMessage:
      name: OrderCreatedEvent
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/OrderCreatedEvent'

Service discovery: Consul registration without thinking about it

The Order Service doesn't know it exists in a cluster. Spring Cloud Consul handles registration automatically at startup:

spring:
  cloud:
    consul:
      enabled: true
      discovery:
        prefer-ip-address: true
        instance-id: ${spring.application.name}:${spring.application.instance_id:${random.value}}
        fail-fast: false

The instance-id with ${random.value} allows multiple replicas to register without collisions. fail-fast: false is worth noting: the service starts even if Consul is temporarily unavailable, rather than refusing to boot — a pragmatic choice for local dev where startup order isn't guaranteed.

When you open the Consul UI after a docker-compose up, the service appears, goes green, and becomes routable through the gateway — no manual step required.

Observability: Micrometer out of the box

Every Spring Boot service in SmartOrder is instrumented with Micrometer. The Actuator and Prometheus endpoints are configured, and the Grafana dashboards in docker/config-services/grafana pick them up automatically — the bootstrap module ensures there's real data flowing from the start.

What you get without writing anything: http_server_requests_seconds latency histograms per endpoint, JVM memory metrics, and Spring Cloud Stream message throughput counters. Custom business metrics are four lines:

Counter.builder("orders.created")
    .tag("tier", customerTier)
    .register(meterRegistry)
    .increment();

That counter shows up in Prometheus and Grafana with zero additional config. The infrastructure is already there.

The full flow, end to end

Let's put it all together. A client calls POST /orders through the Gateway:

Gateway resolves the route from Consul, forwards to an Order Service instance.
api module — the DelegateImpl receives the request via the OpenAPI-generated contract.
business module — the application layer runs the use case, passing the Order aggregate to the Drools engine.
Drools inserts the order and its items as facts, fires all matching rules. If a constraint fails, the use case returns an error response immediately.
If validation passes, the Order is persisted to MongoDB. An OrderOutboxEvent record is saved in the same write, then OutboxSender dispatches the event to RabbitMQ asynchronously via Spring Cloud Stream.
Response goes back as EntityModel<Order> with HAL-FORMS affordances and HTTP 201.
Meanwhile, Inventory Service consumes the OrderCreated CloudEvent from RabbitMQ and reserves stock — fully decoupled, no synchronous dependency.

The consistency problem at step 5 — the classic "what if the broker is down?" — is already handled by the outbox pattern. The event record in MongoDB is the guarantee; the broker delivery is an implementation detail on top of it. A retry scheduler over FAILED events is the natural next piece to add, and a good open contribution.

What's next

We've covered the full Order Service: its module boundaries, the Drools-driven state machine, the custom OpenAPI generator templates that produce real HATEOAS types, HAL-FORMS affordances, and the transactional outbox pattern for reliable event publishing.

Next up: the Inventory Service — the consumer side of that same OrderCreated event, idempotency handling, and what happens when stock is insufficient.

If something here sparked an idea, the repo is open. The issues tab is quiet right now — that's a hint. 🙂

→ github.com/portus84/smartorder-ms

SmartOrder — Part 2: The Services Layer Architecture

Francesco Portus — Wed, 25 Feb 2026 16:59:35 +0000

In the previous article, I introduced SmartOrder as a modern microservices reference platform designed around DDD, REST + HATEOAS, OpenAPI, AsyncAPI, and event-driven principles.

In this article, we focus exclusively on the services layer structure of the repository:

👉 https://github.com/portus84/smartorder-ms/tree/develop/services

This is not a deep dive into individual services — those will be covered in dedicated articles.

Instead, this post explains the architectural blueprint behind the services module and why it is structured this way.

Why a Single `services` Aggregator Module?

Unlike many microservices repositories that split each service into completely separate repositories, SmartOrder adopts a single multi-module Maven structure.

This decision was intentional and driven by:

Blueprint visibility
Consistent dependency management
Architectural governance
Easier local development
Clear separation between shared infrastructure and business services

The services directory acts as a bounded aggregation root for all deployable microservices.

It is not just a folder — it represents the runtime boundary of the platform.

High-Level Structure

The services directory contains:

Multiple Spring Boot microservices
Each service as an independent Maven module
A shared parent for dependency alignment
Strict separation between business logic and infrastructure

Conceptually:

services/
├── service-a
├── service-b
├── service-c
└── pom.xml

Each service:

Is independently deployable
Has its own Spring Boot entry point
Owns its own domain
Exposes REST APIs
Optionally publishes/subscribes to events

Yet they share:

Platform conventions
Dependency versions
Architectural constraints

Architectural Intent

The services module enforces several architectural rules:

1️⃣ Domain Isolation

Each microservice:

Encapsulates its own domain model
Does not access another service’s database
Communicates via:
- REST APIs
- Events (message broker)

This enforces true bounded contexts as described in Domain-Driven Design.

2️⃣ API-First Design

All services follow:

OpenAPI specification for REST contracts
AsyncAPI for event-driven contracts

This means:

APIs are explicit
Contracts are versionable
Consumer-driven development is possible

Services are not “Spring controllers first” — they are contract-first.

3️⃣ Clean Internal Layering

Although we are not describing each service individually, the internal structure of services follows a consistent pattern:

service/
├──api/
├──business/
├──bootstrap/
└── pom.xml

This allows:

Business logic isolation
Framework independence
Testability
Technology replaceability

The services module is therefore not just a deployment unit — it is a DDD enforcement mechanism.

4️⃣ Event-Driven Integration

Services are designed to:

Publish domain events
React to integration events
Remain loosely coupled

This enables:

Horizontal scalability
Independent evolution
Failure isolation

The services layer is built assuming distributed system realities:

Network failures
Eventual consistency
Idempotency
Observability requirements

Why Not Separate Repositories?

A common question:

Why not split each microservice into its own repository?

Because SmartOrder is a reference platform, not just a production system.

The goal is:

To show the blueprint clearly
To allow readers to see cross-service patterns
To simplify learning and experimentation
To enforce architectural coherence

The services module makes the architecture visible.

It turns the repository into:

A living microservices architecture manual.

Governance Through Structure

The services directory enforces governance through:

Parent POM inheritance
Dependency management alignment
Consistent plugin configuration
Shared coding conventions
Architectural symmetry

This prevents:

Version drift
Accidental divergence
Architecture erosion

The structure itself becomes a control mechanism.

Services as Independent Runtime Units

Even though they live in the same repository, services are:

Independently buildable
Independently testable
Independently deployable
Independently scalable

This keeps:

CI/CD pipelines clean
Docker images separated
Infrastructure definitions modular

The mono-repo is organizational.

The services remain microservices at runtime.

Strategic Outcome

The services module achieves a balance between:

Concern	Solution
Blueprint clarity	Single structured repository
Runtime independence	Separate Spring Boot services
Architectural governance	Parent POM + enforced layering
Scalability	Event-driven + REST integration
Evolvability	Domain isolation

This makes SmartOrder:

Educational
Production-ready
Architecturally opinionated
Extensible

What’s Next?

In the next articles, we will:

Explore individual services
Analyze their domain boundaries
Examine REST and event contracts
Discuss persistence strategies
Deep dive into integration patterns

The goal is to progressively unfold the SmartOrder architecture layer by layer.

Stay tuned 🚀

SmartOrder: A Modern Microservices Reference Platform

Francesco Portus — Thu, 12 Feb 2026 17:30:12 +0000

SmartOrder — a production-ready microservices blueprint (for architects & devs)

A quick, hands-on tour of the SmartOrder reference platform: why it’s structured the way it is, how the Docker-based developer experience is designed, and where you can jump in and contribute.

Repository: GitHub

TL;DR — why this repo matters (put this first)

It doesn't want to be just a toy. SmartOrder would like be a full microservices reference platform that aims to be a blueprint for production-grade systems: service discovery, API gateway, messaging, observability, local developer tooling and reproducible environments — all wired together so you can boot everything with a single command.

If you design, build or operate distributed systems, this repo gives you a realistic end-to-end example to read, extend and reuse.

Big-picture architecture (the elevator pitch)

API Gateway: Spring Cloud Gateway acts as a single entry point, dynamically routing using Consul and providing cross-cutting policies (CORS, circuit-breaker fallback, etc.). GitHub+gateway
Service mesh-ish primitives: Consul is used for service discovery and configuration (auto-registration, health checks). GitHub+docker
Business microservices: multiple standalone Spring Boot services (Order, Inventory, Product, …) expose HATEOAS-enabled REST APIs and are instrumented with Micrometer. GitHub+services
Asynchronous communication: RabbitMQ for event-driven messaging (CQRS-friendly, eventual consistency patterns). Kafka is intentionally omitted to keep local dev simple. GitHub+services
Persistence: MongoDB per service for schema-less persistence where appropriate.
Observability & dashboards: a fully dockerized stack (Prometheus, Grafana, InfluxDB, Dozzle, Dashy) with pre-provisioned dashboards.

This combination is designed as a blueprint — an opinionated, repeatable assembly of components you can copy into a real project and evolve.

Platform UIs

Gateway UI

Consul UI

Dashy

Dozzle

Grafana UI

Why a large Maven project (and why not many separate repos)

Maintainers often face a choice: many tiny repositories (one per service) vs a single repository (or multi-module Maven project) that groups related services. This repository chooses the latter to deliver a few concrete advantages for a blueprint:

Single versioned snapshot — everything boots together and the Docker Compose orchestrations match code checked into the repo. That makes local reproducibility and tutorial-style onboarding trivial.
Synchronized dependency management — parent POMs and shared dependencyManagement / pluginManagement reduce version drift across services and simplify CI.
Coordinated local dev environment — the docker/ folder and docker-compose.all.yml orchestrate the full ecosystem so you can run the whole stack with the correct versions of monitoring, messaging and persistence. Trying to coordinate cross-repo snapshots for a demo/blueprint is brittle; a single multi-service Maven project keeps the blueprint faithful.
Blueprint clarity — grouping the services makes it easier to show architecture diagrams, end-to-end flows, and example scenarios without jumping between dozens of independent repos.

(If you prefer a polyrepo for production microservices at scale, you can still take the blueprint and split services later. The repo is intentionally organized to make that extraction straightforward.)

Docker & local dev — the reproducible playground

The Docker setup is central — it’s not an afterthought. The repo exposes a structured docker/ layout and multiple compose files so you can selectively boot only what you need or everything at once:

docker
├── config-services
│   ├── dashy
│   ├── grafana
│   ├── influxdb
│   ├── jmeter
│   ├── prometheus
├── docker-compose.all.yml
├── docker-compose.monitoring.yml
├── docker-compose.persistence.yml

docker-compose.all.yml orchestrates the entire ecosystem (gateway, services, RabbitMQ, Consul, MongoDB, observability tools). The intent: one command to reproduce a realistic environment for debugging, load testing, or demoing features.

Run the full stack (example):

# from repo root (example)
docker-compose -f docker/docker-compose.all.yml up --build

(Exact command and compose file names are in the docker/ folder in the repo.) GitHub+docker

Domain-Driven Design (DDD), REST + HATEOAS, OpenAPI & AsyncAPI

The project follows DDD thinking: services own bounded contexts and encapsulate business responsibilities (orders, inventory, product). That makes the model boundaries and data ownership explicit to anyone reading the code.
REST + HATEOAS: APIs are exposed with HATEOAS-friendly responses so clients can discover resources and transitions (links) instead of relying solely on out-of-band docs.
OpenAPI / AsyncAPI: the repo is organized to document synchronous REST APIs with OpenAPI and asynchronous channels with AsyncAPI (where applicable). That makes automated client generation and message contract validation straightforward.

(You’ll find OpenAPI or API docs and AsyncAPI artifacts in the docs folder and service modules; see the repo link below.)

GitHub+openapi+order

GitHub+openapi-inventory

GitHub+async-api

Testing, quality gates and CI

The project is set up with attention to quality:

Unit tests and integration tests are used to validate both service logic and interactions.
A sonar-project.properties is present — the project is prepared to be analyzed with SonarCloud/ SonarQube for code smells, bugs, and coverage tracking.
Coverage and CI badges are included to communicate health at a glance (see README). The repo is a good place to experiment with mutation testing, contract tests (for messaging), and end-to-end test strategies.

Example — small request flow (Order → Inventory)

Client hits the Gateway: POST /api/orders
Gateway routes to Order Service (route registered via Consul).
Order Service persists the order into its bounded-context DB (Mongo).
Order Service publishes an OrderCreated event to RabbitMQ.
Inventory Service consumes OrderCreated, reserves stock, and may publish StockReserved or StockFailed.
Clients can follow HATEOAS links to query order status or next steps.

This kind of event-driven choreography is implemented in the services and wired up via the Dockerized messaging broker so you can step through it locally.

Why you should read (and contribute)

Architects: read the composition choices (service discovery via Consul, why RabbitMQ for a demo blueprint, observability-first stack) to get ideas for your next architecture review or to compare trade-offs.
Developers: the repo contains tangible examples (Spring Boot apps, HATEOAS patterns, Micrometer instrumentation, Docker Compose orchestration) you can clone and run to learn by doing.
Contributors: tests, docs, and monitoring dashboards are all designed to be extended. Help wanted items you can contribute: sample OpenAPI/AsyncAPI files, additional integration tests (contract tests for messages), example CI workflows, or language-agnostic client examples.

Where to look in the repo

README.md — quick architecture overview and goals. GitHub
docker/ — all the compose files and monitoring stacks (the reproducible dev environment). GitHub+docker
services/ — the individual Spring Boot applications (Order, Inventory, Product, …). GitHub+services

How you can help (suggested first PRs)

Add/extend AsyncAPI docs for message contracts so consumers/producers can be code-generated.
Add contract tests for event messages (e.g., Pact or custom consumer-driven contracts).
Harden the CI workflow with matrixed tests and coverage reporting.
Improve examples for extracting a single service into its own repo (migration guide).
Add sample client SDKs generated from OpenAPI for one service.

Final notes & follow-ups

This post is the first of a short series that will walk through the repository in more detail: next posts will deep-dive into the Docker composition and observability dashboard, then into DDD and the messaging contracts, and finally into testing strategies and a contributor’s guide — coming as soon as possible.

Enjoy exploring the blueprint — contributions welcome!

DEV Community: Francesco Portus

SmartOrder — Part 5: The Commons Layer — Shared Infrastructure Done Right

The three sub-modules at a glance

commons-business: Generic CRUD without the ceremony

The Entity contract

AbstractCrudService: one class to rule them all

ServiceUtils: reflection-based field protection

JPA vs Mongo — two concrete services, zero duplication

commons-service: Where the real magic lives

Custom Jackson deserializers for Spring types

AOP logging with zero configuration

HATEOAS: pluralizing link relations

HATEOASLinkUtils: resolving placeholder base paths

OpenAPI schema cleanup

service-test: A test framework in 3 files

The annotation

How it works: WithTestDataListener

Auto-configuration: zero-config by design

What makes this commons layer unusual

What's next

SmartOrder — Part 4: Inside the Inventory Service

Ownership and boundaries

The domain model and commons integration

Polyglot persistence

Event-driven consumption

Availability check and conditional event publishing

HATEOAS in REST responses

Event-driven workflow: solved challenges

TODO: checkAvailability

Bootstrap and test data (developer hint)

What's next: commons modules

SmartOrder — Part 3: Inside the Order Service

What does the Order Service actually own?

The module structure: three modules, three responsibilities

Business rules with Drools: the state machine lives in .drl files

The rule engine: Strategy pattern over raw sessions

Contract-first: two YAML files, two roles

Where the standard generator falls short: custom extensions + Mustache templates

HATEOAS with affordances: more than just links

The domain event: outbox pattern, not wishful thinking

Service discovery: Consul registration without thinking about it

Observability: Micrometer out of the box

The full flow, end to end

What's next

SmartOrder — Part 2: The Services Layer Architecture

Why a Single services Aggregator Module?

High-Level Structure

Architectural Intent

1️⃣ Domain Isolation

2️⃣ API-First Design

3️⃣ Clean Internal Layering

4️⃣ Event-Driven Integration

Why Not Separate Repositories?

Governance Through Structure

Services as Independent Runtime Units

Strategic Outcome

What’s Next?

SmartOrder: A Modern Microservices Reference Platform

SmartOrder — a production-ready microservices blueprint (for architects & devs)

TL;DR — why this repo matters (put this first)

Big-picture architecture (the elevator pitch)

Platform UIs

Gateway UI

Consul UI

Dashy

Dozzle

Grafana UI

Why a large Maven project (and why not many separate repos)

Docker & local dev — the reproducible playground

Domain-Driven Design (DDD), REST + HATEOAS, OpenAPI & AsyncAPI

Testing, quality gates and CI

Example — small request flow (Order → Inventory)

Why you should read (and contribute)

Where to look in the repo

How you can help (suggested first PRs)

Final notes & follow-ups

TODO: `checkAvailability`

Business rules with Drools: the state machine lives in `.drl` files

Why a Single `services` Aggregator Module?