eva4j 1.0.13 → 1.0.15

package/docs/commands/GENERATE_ENTITIES.md

@@ -19,6 +19,9 @@
 13. [Generated files](#13-generated-files)
 14. [Complete examples](#14-complete-examples)
 15. [Prerequisites and common errors](#15-prerequisites-and-common-errors)
+16. [Declarative endpoints — use case patterns](#16-declarative-endpoints-endpoints--use-case-patterns)
+17. [Consuming external events (listeners:)](#17-consuming-external-events-listeners)
+18. [Synchronous HTTP clients (ports:)](#18-synchronous-http-clients-ports)
 
 ---
 
@@ -375,6 +378,84 @@ entities:
 
 ---
 
+## 7b. Soft Delete
+
+When `hasSoftDelete: true` is set on the aggregate root, eva4j generates logical deletion instead of physical: the record is not removed from the database but stamped with a `deletedAt` timestamp.
+
+> **Scope rule:** `hasSoftDelete` is **only valid on the aggregate root** (`isRoot: true`). Setting it on a secondary entity emits a warning and is silently ignored — secondary entities are deleted physically via CASCADE from the root.
+
+### Syntax
+
+```yaml
+entities:
+  - name: order
+    isRoot: true          # ← mandatory: only root entities support this
+    tableName: orders
+    hasSoftDelete: true   # ✅ enables soft delete
+    audit:
+      enabled: true
+    fields:
+      - name: id
+        type: String
+      - name: orderNumber
+        type: String
+
+  - name: orderItem       # ← secondary entity
+    tableName: order_items
+    # hasSoftDelete: true ← ❌ ignored with warning
+```
+
+### What is generated
+
+| Artefact | `deletedAt` included | Notes |
+|---|---|---|
+| Full constructor (reconstruction) | ✅ | Required to hydrate persisted state |
+| Business constructor (new object) | ❌ | Starts as `null` |
+| `CreateDto` / `CreateCommand` | ❌ | Cannot create an already-deleted object |
+| `ResponseDto` | ❌ | Internal metadata, not exposed in API |
+| `toJpa()` in mapper | ✅ | Persists the timestamp after `softDelete()` |
+
+**Domain entity:**
+```java
+public class Order {
+    private LocalDateTime deletedAt;  // injected automatically
+
+    public void softDelete() {
+        if (this.deletedAt != null) {
+            throw new IllegalStateException("Order is already deleted");
+        }
+        this.deletedAt = java.time.LocalDateTime.now();
+    }
+
+    public boolean isDeleted() {
+        return this.deletedAt != null;
+    }
+}
+```
+
+**JPA entity:**
+```java
+@SQLRestriction("deleted_at IS NULL")   // filters ALL queries automatically
+@Entity
+@Table(name = "orders")
+public class OrderJpa extends AuditableEntity {
+    private LocalDateTime deletedAt;
+}
+```
+
+**DeleteCommandHandler** (generated when `hasSoftDelete: true`):
+```java
+// Finds → marks → saves — never deleteById
+Order order = repository.findById(id)
+    .orElseThrow(() -> new OrderNotFoundException(id));
+order.softDelete();
+repository.save(order);
+```
+
+> `deletedAt` **must not be defined manually** in `fields:` — the generator injects it automatically.
+
+---
+
 ## 8. Relationships
 
 ### Properties
@@ -624,27 +705,83 @@ Java condition evaluated in the transition method. If the expression is `true`,
 
 ## 11. Domain events
 
-Events are declared under the aggregate (at the same level as `entities:`, `enums:`, `valueObjects:`).
+Events are declared under the aggregate (at the same level as `entities:`, `enums:`, `valueObjects:`). Use the optional `triggers` property to connect an event to one or more state transition methods — the generator then emits `raise()` automatically inside each method.
 
 ```yaml
 aggregates:
   - name: Order
+    enums:
+      - name: OrderStatus
+        initialValue: DRAFT
+        transitions:
+          - from: DRAFT
+            to: PLACED
+            method: place
+          - from: PLACED
+            to: CANCELLED
+            method: cancel
+        values: [DRAFT, PLACED, CANCELLED]
     events:
       - name: OrderPlaced
+        topic: ORDER_PLACED     # preferred: explicit — must match listeners[].topic in consumers
+                                # default derivation: strips 'Event' suffix → OrderPlacedEvent → ORDER_PLACED
+        triggers:
+          - place             # transition method name that publishes this event
         fields:
+          # orderId declared for cross-module Kafka consumers — generator maps it to event.getAggregateId()
+          - name: orderId
+            type: String
           - name: customerId
             type: String
           - name: totalAmount
             type: BigDecimal
+          - name: placedAt
+            type: LocalDateTime
       - name: OrderCancelled
+        topic: ORDER_CANCELLED  # preferred: explicit topic
+        triggers:
+          - cancel
         fields:
-          - name: reason
+          - name: reason      # unresolvable → null /* TODO: provide reason */
             type: String
     entities:
       - name: Order
+        isRoot: true
         # ...
 ```
 
+### `triggers` — argument resolution rules (in order)
+
+| Field condition | Generated argument |
+|---|---|
+| Always (first arg — `aggregateId` from `DomainEvent` base) | `this.getId()` |
+| Name = `{entityName}Id` (e.g. `orderId` in `Order`) | **Skipped in Domain Event class** — mapped to `event.getAggregateId()` in the Integration Event handler |
+| Name matches a field of the entity | `this.get{Field}()` |
+| Name ends in `At` + type `LocalDateTime` | `LocalDateTime.now()` |
+| Not resolvable | `null /* TODO: provide {fieldName} */` |
+
+> **Convention:** Declare `{entityName}Id` in `events[].fields` when the event **crosses module boundaries via Kafka** — it is required so the id travels in the Integration Event payload. The generator automatically maps it to `event.getAggregateId()` in the handler, preventing duplication in the internal Domain Event class. If the event is only consumed within the same bounded context (Spring event bus), `{entityName}Id` can be omitted since `getAggregateId()` is already available.
+
+### `topic` — Kafka topic name for the event
+
+Optional but **recommended**. Declares the Kafka topic name for this event explicitly.
+
+```yaml
+events:
+  - name: OrderPlacedEvent
+    topic: ORDER_PLACED        # ✅ preferred: explicit, matches listeners[].topic in consumers
+    triggers: [place]
+    fields: [...]
+```
+
+**Default derivation (when `topic:` is omitted):** the generator strips the `Event` suffix from the class name before converting to SCREAMING_SNAKE_CASE:
+- `OrderPlacedEvent` → `ORDER_PLACED` ✓
+- `OrderCancelled` *(no suffix)* → `ORDER_CANCELLED` ✓
+
+**Why prefer explicit `topic:`:** when a consumer module declares `listeners[].topic: ORDER_PLACED`, the value must match the producer's topic exactly. Declaring it explicitly in both places eliminates any risk of mismatch and makes the contract visible without having to understand the derivation rule.
+
+If an event has **no `triggers`**, the developer must call `raise()` manually inside the business method.
+
 ### Generated files
 
 | File | Description |
@@ -658,29 +795,52 @@ aggregates:
 
 ### Generated event
 
+Fields declared as `{entityName}Id` are excluded from the **Domain Event class** (the aggregate id is already available via `getAggregateId()` inherited from `DomainEvent`), but they **are included** in the Integration Event record and the Kafka payload — the handler maps them to `event.getAggregateId()` automatically.
+
 ```java
 public final class OrderPlaced extends DomainEvent {
+    // aggregateId (= orderId) inherited from DomainEvent — not repeated here
     private final String customerId;
     private final BigDecimal totalAmount;
+    private final LocalDateTime placedAt;
 
-    public OrderPlaced(String customerId, BigDecimal totalAmount) {
+    public OrderPlaced(String aggregateId, String customerId, BigDecimal totalAmount, LocalDateTime placedAt) {
+        super(aggregateId);
         this.customerId = customerId;
         this.totalAmount = totalAmount;
+        this.placedAt = placedAt;
     }
 
     // getters
 }
 ```
 
-### How to raise an event in the entity
+### How to raise an event — auto-generated via `triggers`
+
+When `triggers` is declared, the generator emits the `raise()` call automatically inside each transition method:
+
+```java
+public void place() {
+    this.status = this.status.transitionTo(OrderStatus.PLACED);
+    raise(new OrderPlaced(this.getId(), this.getCustomerId(), this.getTotalAmount(), LocalDateTime.now()));
+    //                    ^—aggregateId  ^—customerId         ^—totalAmount         ^—placedAt
+}
+
+public void cancel() {
+    this.status = this.status.transitionTo(OrderStatus.CANCELLED);
+    raise(new OrderCancelled(this.getId(), null /* TODO: provide reason */));
+}
+```
+
+For events **without `triggers`**, call `raise()` manually:
 
 ```java
 public class Order {
     private final List<DomainEvent> domainEvents = new ArrayList<>();
 
-    public void place(String customerId, BigDecimal totalAmount) {
+    public void someBusinessAction() {
         // business logic...
-        raise(new OrderPlaced(customerId, totalAmount));
+        raise(new OrderPlaced(this.getId(), this.customerId, this.totalAmount, LocalDateTime.now()));
     }
 
     protected void raise(DomainEvent event) {
@@ -695,6 +855,14 @@ public class Order {
 }
 ```
 
+### Validator checks
+
+| Code | Severity | Condition |
+|------|----------|-----------|
+| C2-001 | warning | Transition without a use-case — silenced when `triggers` is present |
+| C2-004 | error | `triggers` references a method that does not exist in any transition |
+| C2-005 | info | Transition method with no associated event — consider adding `triggers` |
+
 ---
 
 ## 12. Multiple aggregates
@@ -837,10 +1005,19 @@ aggregates:
 
     events:
       - name: OrderPlaced
+        triggers:
+          - confirm
         fields:
+          # orderId declared for cross-module Kafka consumers — generator maps it to event.getAggregateId()
+          - name: orderId
+            type: String
           - name: customerId
             type: String
+          - name: confirmedAt
+            type: LocalDateTime
       - name: OrderCancelled
+        triggers:
+          - cancel
         fields:
           - name: reason
             type: String
@@ -907,3 +1084,615 @@ aggregates:
 | `Column 'x_id' is duplicated` | ManyToOne defined manually + auto-generated | Remove the manual ManyToOne; let eva4j generate it |
 | File not regenerated | File was manually modified (checksum) | Use `--force` to overwrite |
 | Import errors | Field `type` doesn't match name in `enums:` or `valueObjects:` | Verify names match exactly |
+
+---
+
+## 16. Declarative endpoints (`endpoints:`) — Use case patterns
+
+When `domain.yaml` includes an `endpoints:` section, the generator examines each `useCase` name and classifies it semantically before generating code. This determines whether a full, working implementation or a scaffold stub is produced.
+
+### 16.1 Pattern table
+
+| Pattern | Category | Recognition condition | What is generated |
+|---------|----------|----------------------|-------------------|
+| `Create{Aggregate}` | **standard** | Exact string match | Full `CreateCommand` + `CreateCommandHandler` (`ApplicationMapper.fromCommand → save`) |
+| `Update{Aggregate}` | **standard** | Exact string match | Full `UpdateCommand` + `UpdateCommandHandler` |
+| `Delete{Aggregate}` | **standard** | Exact string match | Full `DeleteCommand` + `DeleteCommandHandler` |
+| `Get{Aggregate}` | **standard** | Exact string match | Full `GetQuery` + `GetQueryHandler` (find + `mapper.toDto`) |
+| `FindAll{Aggregate}s` | **standard** | Exact string match (trailing literal `s`) | Full `ListQuery` + `ListQueryHandler` (paginated) |
+| `{MethodPascal}{Aggregate}` | **transition** | `MethodPascal` is `toPascalCase(transitions[n].method)` for any enum in the aggregate | Full `TransitionCommand(id)` + handler that calls `entity.{method}() → save()` |
+| `Add{EntityName}` | **subEntityAdd** | `EntityName` is the `target` of a `OneToMany` relationship on the root | Full `AddCommand(id, entityFields…)` + handler that calls `entity.add{Entity}(new {Entity}(…)) → save()` |
+| `Remove{EntityName}` | **subEntityRemove** | Same `target` from a `OneToMany` relationship | Full `RemoveCommand(id, itemId)` + handler that calls `entity.remove{Entity}ById(itemId) → save()` |
+| `FindAll{Aggregate}sBy{FieldPascal}` | **findBy** | `FieldPascal` is `toPascalCase(fieldName)` for any field in the root entity | Full `FindByQuery` + `FindByQueryHandler` + `findBy{FieldPascal}` added to `{Aggregate}Repository`, `{Aggregate}RepositoryImpl`, and `{Aggregate}JpaRepository` |
+| _anything else_ | **scaffold** | No pattern matched | `*Command(id)` or `*Query(id)` + handler that throws `UnsupportedOperationException` with a TODO comment |
+
+> **Note on `FindAll{Aggregate}s`:** The trailing `s` is a literal character. For `Aggregate = Order` the standard name is `FindAllOrders` (not `FindAllOrder`). Irregular plurals are not supported — use the exact pattern or it will be classified as scaffold.
+
+### 16.2 Transition pattern in detail
+
+Enumerate state transitions in the `enums:` block using `transitions`:
+
+```yaml
+enums:
+  - name: OrderStatus
+    transitions:
+      - from: PENDING
+        to: CONFIRMED
+        method: confirm        # → recognized as ConfirmOrder (PascalCase(confirm) + Order)
+      - from: [PENDING, CONFIRMED]
+        to: CANCELLED
+        method: cancel         # → CancelOrder
+      - from: CONFIRMED
+        to: SHIPPED
+        method: ship           # → ShipOrder
+    values: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
+```
+
+Declare the corresponding use cases in `endpoints:`:
+
+```yaml
+endpoints:
+  basePath: /orders
+  versions:
+    - version: v1
+      operations:
+        - method: PUT
+          path: /{id}/confirm
+          useCase: ConfirmOrder    # ← transition pattern: confirm + Order
+          type: command
+        - method: PUT
+          path: /{id}/cancel
+          useCase: CancelOrder
+          type: command
+```
+
+**Generated output:**
+
+```java
+// ConfirmOrderCommand.java
+public record ConfirmOrderCommand(String id) implements Command {}
+
+// ConfirmOrderCommandHandler.java
+@Transactional
+public void handle(ConfirmOrderCommand command) {
+    Order entity = repository.findById(command.id())
+            .orElseThrow(() -> new NotFoundException("Order not found with id: " + command.id()));
+    entity.confirm();   // ← the domain method from transitions[].method
+    repository.save(entity);
+}
+```
+
+### 16.3 Sub-entity add/remove pattern in detail
+
+Requirements:
+- A `OneToMany` relationship must be declared on the root entity pointing to the target entity.
+- The aggregate root must expose `add{EntityName}({EntityName} item)` and `remove{EntityName}ById(String id)` domain methods (generated automatically by `eva g entities`).
+
+```yaml
+# aggregates: section
+relationships:
+  - type: OneToMany
+    target: OrderItem          # ← entityName used to match Add/Remove pattern
+    fieldName: items
+    ...
+
+# endpoints: section
+operations:
+  - method: POST
+    path: /{id}/items
+    useCase: AddOrderItem      # ← Add + OrderItem (target name)
+    type: command
+  - method: DELETE
+    path: /{id}/items/{itemId}
+    useCase: RemoveOrderItem   # ← Remove + OrderItem
+    type: command
+```
+
+**Generated output:**
+
+```java
+// AddOrderItemCommand.java — fields taken from OrderItem (non-id, non-audit, non-readOnly)
+public record AddOrderItemCommand(
+    String id,
+    String productId,
+    String productName,
+    Integer quantity,
+    BigDecimal unitPrice
+) implements Command {}
+
+// AddOrderItemCommandHandler.java
+@Transactional
+public void handle(AddOrderItemCommand command) {
+    Order entity = repository.findById(command.id()) ...;
+    OrderItem item = new OrderItem(command.productId(), command.productName(),
+                                   command.quantity(), command.unitPrice());
+    entity.addOrderItem(item);
+    repository.save(entity);
+}
+
+// RemoveOrderItemCommand.java
+public record RemoveOrderItemCommand(String id, String itemId) implements Command {}
+
+// RemoveOrderItemCommandHandler.java
+@Transactional
+public void handle(RemoveOrderItemCommand command) {
+    Order entity = repository.findById(command.id()) ...;
+    entity.removeOrderItemById(command.itemId());
+    repository.save(entity);
+}
+```
+
+### 16.4 FindBy pattern in detail
+
+Strict pattern: `FindAll{Aggregate}sBy{FieldPascal}` — both parts are required.
+
+When detected, the generator:
+1. Creates a paginated `FindBy{Field}Query` + `FindBy{Field}QueryHandler`.
+2. Re-generates `{Aggregate}Repository.java` (domain interface), `{Aggregate}JpaRepository.java`, and `{Aggregate}RepositoryImpl.java` with the `findBy{FieldPascal}(FieldType value, Pageable pageable)` method added. Checksum protection still applies — manually modified files are skipped unless `--force` is used.
+
+```yaml
+# Root entity field
+fields:
+  - name: customerId
+    type: String
+
+# Endpoint
+operations:
+  - method: GET
+    path: /customer/{customerId}
+    useCase: FindAllOrdersByCustomerId   # ← FindAll + Order + s + By + CustomerId
+    type: query
+```
+
+**Generated output:**
+
+```java
+// FindAllOrdersByCustomerIdQuery.java
+public record FindAllOrdersByCustomerIdQuery(
+    String customerId, int page, int size, String sortBy, String sortDirection
+) implements Query<PagedResponse<OrderResponseDto>> {}
+
+// OrderRepository.java (domain interface — method appended)
+Page<Order> findByCustomerId(String customerId, Pageable pageable);
+
+// OrderJpaRepository.java (Spring Data JPA — method auto-implemented)
+Page<OrderJpa> findByCustomerId(String customerId, Pageable pageable);
+```
+
+### 16.5 Scaffold (fallback)
+
+Any `useCase` name that does not match any pattern above becomes a scaffold. A scaffold generates:
+
+- A minimal `{UseCase}Command(String id)` or `{UseCase}Query(String id)` record.
+- A handler that throws `UnsupportedOperationException` and includes a step-by-step TODO comment.
+
+This is intentional: the developer fills in the custom business logic while the wiring (registration, mediator dispatch, controller method) is already in place.
+
+### 16.6 Naming rules
+
+| What | Convention | Example |
+|------|-----------|---------|
+| Aggregate name | PascalCase | `Order` |
+| Use case name in YAML | PascalCase | `ConfirmOrder`, `FindAllOrdersByCustomerId` |
+| Transition method in YAML | camelCase | `confirm`, `cancelOrder` |
+| Pattern `{MethodPascal}` | `toPascalCase(method)` | `confirm` → `Confirm` |
+| Pattern `{FieldPascal}` | `toPascalCase(fieldName)` | `customerId` → `CustomerId` |
+| Sub-entity target | PascalCase (must match entity `name:`) | `OrderItem` |
+
+---
+
+## 17. Consuming external events (`listeners:`)
+
+The `listeners:` section declares the integration events that this module **consumes** from external producers. It lives at the **root level** of `domain.yaml` as a sibling of `aggregates:`, because it is an infrastructure/integration concern rather than a domain concern.
+
+> **Requires a broker.** Files are only generated when `eva add kafka-client` has been executed in the project. Without a broker, the section is silently ignored.
+
+### Syntax
+
+```yaml
+# Root level — sibling of aggregates:
+listeners:
+  - event: PaymentApprovedEvent    # PascalCase + Event suffix
+    producer: payments             # Module that produces the event (documentary only)
+    topic: PAYMENT_APPROVED        # Kafka topic — required in standalone modules
+    useCase: ConfirmOrder          # Use case invoked when the event is received
+    fields:                        # Payload fields of the Integration Event
+      - name: orderId
+        type: String
+      - name: approvedAt
+        type: LocalDateTime
+      - name: details
+        type: PaymentDetails       # Object field → declare in nestedTypes:
+    nestedTypes:                   # Optional: auxiliary records for object-typed fields
+      - name: paymentDetails       # camelCase → PascalCase in the generated record
+        fields:
+          - name: paymentId
+            type: String
+          - name: amount
+            type: BigDecimal
+```
+
+### Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `event` | ✅ | Event name in PascalCase with `Event` suffix |
+| `producer` | ✅ | Module that produces the event (documentary reference, no code generated) |
+| `topic` | ✅ | Kafka topic. With `system.yaml` can be inferred; in **standalone** modules it is mandatory. |
+| `useCase` | ✅ | Use case name that handles the event (PascalCase) |
+| `fields` | ✅ | Payload fields; generates the `IntegrationEvent` record and types the dispatched Command |
+| `nestedTypes` | ❌ | Auxiliary record classes for object-typed fields in `fields:`. Each entry generates a separate `.java` record in `application/events/`. |
+
+### Generated files
+
+For each `listeners:` entry, eva4j generates **5 files** (plus one record per `nestedTypes:` entry):
+
+| # | File | Location | Description |
+|---|------|----------|-------------|
+| 0 | `{NestedName}.java` *(per nestedType)* | `application/events/` | Auxiliary record for object-typed fields |
+| 1 | `{Name}IntegrationEvent.java` | `application/events/` | Typed contract record (documentation + tests) |
+| 2 | `{Name}KafkaListener.java` | `infrastructure/kafkaListener/` | `@KafkaListener` — deserializes and dispatches |
+| 3 | `kafka.yaml` *(all envs)* | `resources/parameters/*/` | Topic registered under `topics:` |
+| 4 | `{UseCase}Command.java` | `application/commands/` | Typed command dispatched from the listener |
+| 5 | `{UseCase}CommandHandler.java` | `application/usecases/` | Handler stub (implement business logic here) |
+
+### Generated code example
+
+**`PaymentDetails.java`** — `application/events/` (from `nestedTypes:`)
+```java
+public record PaymentDetails(
+    String paymentId,
+    BigDecimal amount
+) {}
+```
+
+**`PaymentApprovedIntegrationEvent.java`** — `application/events/`
+```java
+public record PaymentApprovedIntegrationEvent(
+    String orderId,
+    LocalDateTime approvedAt,
+    PaymentDetails details
+) {}
+```
+
+**`ConfirmOrderCommand.java`** — `application/commands/`
+```java
+import com.example.orders.application.events.PaymentDetails;
+
+public record ConfirmOrderCommand(
+    String orderId,
+    LocalDateTime approvedAt,
+    PaymentDetails details
+) implements Command {}
+```
+
+**`PaymentApprovedKafkaListener.java`** — `infrastructure/kafkaListener/`
+```java
+import com.example.orders.application.events.PaymentDetails;
+
+@Component
+public class PaymentApprovedKafkaListener {
+
+    private final UseCaseMediator useCaseMediator;
+    private final ObjectMapper objectMapper;
+
+    @Value("${topics.payment-approved}")
+    private String paymentApprovedTopic;
+
+    public PaymentApprovedKafkaListener(UseCaseMediator useCaseMediator,
+                                        ObjectMapper objectMapper) {
+        this.useCaseMediator = useCaseMediator;
+        this.objectMapper = objectMapper;
+    }
+
+    @KafkaListener(topics = "${topics.payment-approved}")
+    public void handle(EventEnvelope<Map<String, Object>> event, Acknowledgment ack) {
+        String orderId = objectMapper.convertValue(event.data().get("orderId"), String.class);
+        LocalDateTime approvedAt = objectMapper.convertValue(
+                event.data().get("approvedAt"), LocalDateTime.class);
+        PaymentDetails details = objectMapper.convertValue(
+                event.data().get("details"), PaymentDetails.class);
+        useCaseMediator.dispatch(new ConfirmOrderCommand(orderId, approvedAt, details));
+        ack.acknowledge();
+    }
+}
+```
+
+**`ConfirmOrderCommandHandler.java`** — `application/usecases/`
+```java
+@ApplicationComponent
+public class ConfirmOrderCommandHandler implements CommandHandler<ConfirmOrderCommand> {
+
+    @Override
+    public void handle(ConfirmOrderCommand command) {
+        // TODO: implement ConfirmOrder business logic
+        throw new UnsupportedOperationException("ConfirmOrderCommandHandler not yet implemented");
+    }
+}
+```
+
+### `topic:` resolution rule
+
+| Scenario | Behaviour |
+|----------|-----------|
+| Standalone module (only `domain.yaml`) | `topic:` **required** — no other source of truth |
+| Project with `system.yaml` | `topic:` optional; inferred from `integrations.async[].topic` |
+| `topic:` declared explicitly with `system.yaml` | Declared value takes **precedence** over inference |
+
+### Deserialization — how it works
+
+The Kafka consumer delivers an `EventEnvelope<Map<String, Object>>`. The generated listener extracts each field using `objectMapper.convertValue()`, which handles:
+
+- Primitives and strings: `convertValue(map.get("field"), String.class)`
+- Dates: `convertValue(map.get("date"), LocalDateTime.class)` — requires Jackson JavaTime module
+- Objects / nested types: `convertValue(map.get("details"), PaymentDetails.class)` — works automatically for Java records
+- Lists: `convertValue(map.get("items"), typeFactory.constructCollectionType(List.class, ItemType.class))`
+
+### `nestedTypes:` — when to use it
+
+Use `nestedTypes:` when one of the `fields:` entries is a structured object (not a primitive Java type). Each entry generates a Java record in `application/events/` that is automatically imported in both the `KafkaListener` and the `Command`.
+
+The name is declared in `camelCase` and normalised to `PascalCase` by the generator:
+```yaml
+nestedTypes:
+  - name: paymentDetails    # → PaymentDetails.java
+    fields:
+      - name: paymentId
+        type: String
+      - name: amount
+        type: BigDecimal
+```
+
+`{Name}IntegrationEvent.java` does **not** need an import for nested types because it lives in the same `application/events/` package.
+
+### Contrast: producing vs. consuming
+
+```
+domain.yaml
+├── aggregates:
+│   └── [Aggregate]
+│       └── events:      → Domain Events that this module PRODUCES (domain/models/events/)
+│
+└── listeners:           → Integration Events that this module CONSUMES (infrastructure/kafkaListener/)
+```
+
+---
+
+## 18. Synchronous HTTP clients (`ports:`)
+
+The `ports:` section declares synchronous HTTP dependencies — external services this module **calls** via Feign. It lives at the **root level** of `domain.yaml` as a sibling of `aggregates:` and `listeners:`, because it represents a secondary port of the hexagonal architecture (not domain logic).
+
+> **Requires OpenFeign.** The generated `FeignClient` and `FeignAdapter` depend on `spring-cloud-starter-openfeign`. The project must include it as a dependency.
+
+### 18.1 Syntax
+
+```yaml
+# Root level — sibling of aggregates: and listeners:
+# One entry = one method. Entries with the same service: form a single FeignClient.
+
+ports:
+  - name: findScreeningById            # method name (camelCase)
+    service: ScreeningService          # groups into one interface/FeignClient (PascalCase)
+    target: screenings                 # destination module (documentary reference only)
+    baseUrl: http://localhost:8081     # → parameters/*/urls.yaml (first entry per service only)
+    http: GET /screenings/{id}         # HTTP verb + path
+    fields:                            # response fields → domain model + infra DTO
+      - name: id
+        type: String
+      - name: startTime
+        type: LocalDateTime
+
+  - name: findAvailableSeats
+    service: ScreeningService          # same service → same FeignClient
+    target: screenings
+    http: GET /screenings/{id}/seats
+    returnList: true                   # → List<Seat> in port interface
+    domainType: Seat                   # override auto-derived type (default: FindAvailableSeat)
+    fields:
+      - name: seatId
+        type: String
+      - name: seatType
+        type: String
+
+  - name: processPayment
+    service: PaymentGateway
+    target: payment-gateway-external
+    baseUrl: https://api.payments.example.com
+    http: POST /payments
+    body:                              # @RequestBody → ProcessPaymentRequestDto.java
+      - name: amount
+        type: BigDecimal
+      - name: paymentMethod
+        type: PaymentMethodInput       # object field → declare in nestedTypes:
+    nestedTypes:
+      - name: paymentMethodInput       # camelCase → PascalCase record
+        fields:
+          - name: type
+            type: String
+          - name: cardToken
+            type: String
+    fields:                            # response fields → Payment domain model + infra DTO
+      - name: paymentId
+        type: String
+      - name: status
+        type: String
+
+  - name: cancelPayment
+    service: PaymentGateway
+    target: payment-gateway-external
+    http: DELETE /payments/{id}
+    # fields: omitted → void return
+```
+
+### 18.2 Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `name` | ✅ | Method name in camelCase. Auto-derives the domain type (e.g. `findScreeningById` → `Screening`). |
+| `service` | ✅ | PascalCase service name. All entries sharing the same `service:` are grouped into one FeignClient. |
+| `target` | ✅ | Destination module or service name (documentary reference — no code generated). |
+| `baseUrl` | ❌ | Base URL for the service. Declare only on the **first entry** of each `service:`. Becomes a `urls.yaml` property. Defaults to `http://localhost:8080` with a warning if omitted. |
+| `http` | ✅ | `VERB /path` (e.g. `GET /users/{id}`, `POST /payments`). Path variables are `@PathVariable`. |
+| `fields` | ❌ | Response payload fields. Generates a domain model record and an infra DTO. Omit for `void` return. |
+| `domainType` | ❌ | Overrides the domain type name auto-derived from `name`. Use when the default derivation is ambiguous or wrong. |
+| `returnList` | ❌ | `true` → return type is `List<{DomainType}>` in the interface and `List<{InfraDto}>` in the FeignClient. Default: `false`. |
+| `body` | ❌ | Request body fields (POST/PUT/PATCH only). Generates a `{MethodPascal}RequestDto.java`. Ignored with a warning on GET/DELETE. |
+| `nestedTypes` | ❌ | Auxiliary record classes for object-typed fields in `body:`. Each entry generates a Java record in `application/dtos/`. |
+
+### 18.3 Domain type derivation
+
+The domain type is derived automatically from the method name: the leading verb is stripped and the aggregate/entity name is extracted.
+
+| Method name | Auto-derived type | Override needed? |
+|-------------|------------------|-----------------|
+| `findScreeningById` | `Screening` | No |
+| `findAvailableSeats` | `AvailableSeat` | Yes — `domainType: Seat` |
+| `processPayment` | `Payment` | No |
+| `findPaymentStatus` | `PaymentStatus` | Yes — avoids collision with `Payment` if both exist |
+
+> **Rule:** if two methods in the same `service:` derive the same domain type, `generate entities` will fail. Declare `domainType:` on one of them to resolve the collision.
+
+### 18.4 Generated files
+
+**Per unique `service:` name:**
+
+| File | Description |
+|------|-------------|
+| `domain/repositories/{ServiceName}.java` | Secondary port interface — returns domain models |
+| `infrastructure/adapters/{service}/{ServiceName}FeignClient.java` | Typed Feign interface — returns infra DTOs |
+| `infrastructure/adapters/{service}/{ServiceName}FeignAdapter.java` | `@Component implements {ServiceName}` — ACL mapper |
+| `infrastructure/adapters/{service}/{ServiceName}FeignConfig.java` | Feign timeouts configuration |
+| `parameters/*/urls.yaml` | Base URL registered under a property key |
+
+**Per unique domain model derived from methods with `fields:`:**
+
+| File | Description |
+|------|-------------|
+| `domain/models/{service}/{DomainType}.java` | Domain model record (internal abstraction — ACL) |
+
+**Per method:**
+
+| File | Condition |
+|------|-----------|
+| `infrastructure/adapters/{service}/{MethodPascal}Dto.java` | When `fields:` present — infra DTO (external shape) |
+| `application/dtos/{MethodPascal}RequestDto.java` | When `body:` present (POST/PUT/PATCH) |
+| `application/dtos/{NestedTypePascal}.java` | When `nestedTypes:` declared |
+
+### 18.5 ACL pattern
+
+The generated code follows the Anti-Corruption Layer (ACL) pattern to isolate the domain from external API shapes.
+
+```
+External API shape (infra DTO)          Domain abstraction
+────────────────────────────           ──────────────────
+infrastructure/adapters/{service}/      domain/models/{service}/
+  {MethodPascal}Dto.java           →      {DomainType}.java
+  {ServiceName}FeignClient.java    →    domain/repositories/{ServiceName}.java
+  {ServiceName}FeignAdapter.java   (maps DTO → domain model inline)
+```
+
+When the external API changes its field names or structure, **only the adapter is modified** — the domain model and the port interface stay stable.
+
+### 18.6 Generated code example
+
+**`ScreeningService.java`** — `domain/repositories/` (port interface returning domain models)
+```java
+public interface ScreeningService {
+    Screening findScreeningById(String id);
+    List<Seat> findAvailableSeats(String id);
+}
+```
+
+**`ScreeningServiceFeignClient.java`** — `infrastructure/adapters/screeningService/`
+```java
+@FeignClient(name = "screeningService", url = "${urls.screening-service}")
+public interface ScreeningServiceFeignClient {
+
+    @GetMapping("/screenings/{id}")
+    FindScreeningByIdDto findScreeningById(@PathVariable("id") String id);
+
+    @GetMapping("/screenings/{id}/seats")
+    List<FindAvailableSeatsDto> findAvailableSeats(@PathVariable("id") String id);
+}
+```
+
+**`ScreeningServiceFeignAdapter.java`** — `infrastructure/adapters/screeningService/`
+```java
+@Component
+public class ScreeningServiceFeignAdapter implements ScreeningService {
+
+    private final ScreeningServiceFeignClient feignClient;
+
+    public ScreeningServiceFeignAdapter(ScreeningServiceFeignClient feignClient) {
+        this.feignClient = feignClient;
+    }
+
+    @Override
+    public Screening findScreeningById(String id) {
+        return toScreening(feignClient.findScreeningById(id));
+    }
+
+    @Override
+    public List<Seat> findAvailableSeats(String id) {
+        return feignClient.findAvailableSeats(id)
+                .stream().map(this::toSeat).collect(Collectors.toList());
+    }
+
+    private Screening toScreening(FindScreeningByIdDto dto) {
+        return new Screening(dto.id(), dto.startTime());
+    }
+
+    private Seat toSeat(FindAvailableSeatsDto dto) {
+        return new Seat(dto.seatId(), dto.seatType());
+    }
+}
+```
+
+**`Screening.java`** — `domain/models/screeningService/` (domain-side record)
+```java
+public record Screening(String id, LocalDateTime startTime) {}
+```
+
+### 18.7 `nestedTypes:` — when to use it
+
+Use `nestedTypes:` under a port entry when one of the `body:` fields is a structured object (not a primitive). Each `nestedTypes:` entry generates a Java record in `application/dtos/` that is used by the request DTO.
+
+```yaml
+- name: processPayment
+  service: PaymentGateway
+  http: POST /payments
+  body:
+    - name: amount
+      type: BigDecimal
+    - name: paymentMethod
+      type: PaymentMethodInput   # object → declare in nestedTypes:
+  nestedTypes:
+    - name: paymentMethodInput   # → PaymentMethodInput.java in application/dtos/
+      fields:
+        - name: type
+          type: String
+        - name: cardToken
+          type: String
+```
+
+### 18.8 `baseUrl:` resolution rule
+
+| Scenario | Behaviour |
+|----------|-----------|
+| `baseUrl:` on the first entry of a `service:` | Registered in `parameters/*/urls.yaml` as `urls.{service-kebab}` |
+| `baseUrl:` omitted for all entries of a `service:` | Warning printed; defaults to `http://localhost:8080` |
+| `baseUrl:` on non-first entry of a `service:` | Ignored — only the first entry's value is used |
+
+### 18.9 Contrast: async vs sync
+
+```
+domain.yaml
+├── aggregates:
+│   └── [Aggregate]
+│       └── events:     → Domain Events that this module PRODUCES  (async / broker)
+│
+├── listeners:          → Integration Events that this module CONSUMES (async / broker)
+│
+└── ports:              → External HTTP services that this module CALLS (sync / Feign)
+```
+