Common Module Structure

The common module is the shared vocabulary of your pipeline. It carries the types and mappings that every service agrees on.

What Belongs Here

• Domain types: business objects used by services.
• DTOs: transport-friendly shapes for REST or persistence.
• gRPC messages and services: generated from proto definitions shared across services.
• Shared mappers: MapStruct mappers that convert domain ↔ DTO ↔ gRPC.
• Shared helpers: conversion utilities used by multiple mappers.

Example Layout

common/
└── src/main/java/com/example/app/common/
    ├── domain/
    ├── dto/
    ├── grpc/           # generated by protobuf plugin
    ├── mapper/
    └── util/

Mapper Example

@Mapper(
    componentModel = "jakarta",
    uses = {CommonConverters.class},
    unmappedTargetPolicy = ReportingPolicy.WARN
)
public interface PaymentRecordMapper
    extends Mapper<PaymentRecordGrpc, PaymentRecordDto, PaymentRecord> {
}

Guidelines

• Keep service-specific mappers inside the service module.
• Keep gRPC/proto types in common so all services share one contract.
• Avoid putting step implementations in common; keep them in service modules.