eva4j 1.0.13 → 1.0.15

package/templates/base/root/skill-build-domain-yaml-references-generate-entities.md.ejs

@@ -0,0 +1,1663 @@
+# Command `generate entities` (alias: `g entities`)
+
+---
+
+## Table of Contents
+
+1. [Description and purpose](#1-description-and-purpose)
+2. [Syntax and YAML location](#2-syntax-and-yaml-location)
+3. [Base domain.yaml structure](#3-base-domainyaml-structure)
+4. [Supported data types](#4-supported-data-types)
+5. [Field properties](#5-field-properties)
+6. [JSR-303 Validations](#6-jsr-303-validations)
+7. [Auditing](#7-auditing)
+8. [Relationships](#8-relationships)
+9. [Value Objects](#9-value-objects)
+10. [Enums and state transitions](#10-enums-and-state-transitions)
+11. [Domain events](#11-domain-events)
+12. [Multiple aggregates](#12-multiple-aggregates)
+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 (`endpoints:`)](#16-declarative-endpoints-endpoints---use-case-patterns)
+17. [Consuming external events (`listeners:`)](#17-consuming-external-events-listeners)
+18. [HTTP outbound clients (`ports:`)](#18-http-outbound-clients-ports)
+
+---
+
+## 1. Description and purpose
+
+`generate entities` is the core command of eva4j. From a `domain.yaml` file, it generates the complete hexagonal architecture for the module:
+
+- **Domain layer** – Entities, Value Objects, Enums, repository interfaces
+- **Application layer** – Commands, Queries, handlers, DTOs, mappers
+- **Infrastructure layer** – JPA entities, Spring Data repositories, repository implementations, REST controllers
+
+The generator understands relationships, auditing, field visibility, validations, state transitions, and domain events.
+
+---
+
+## 2. Syntax and YAML location
+
+```bash
+eva generate entities <module>
+eva g entities <module>          # short alias
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `<module>` | Yes | Module name (must already exist in the project) |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Overwrite files that have developer changes |
+
+### YAML location
+
+The file is read from:
+
+```
+src/main/java/<package>/<module>/domain.yaml
+```
+
+> The generator detects developer changes via checksums. If a file was manually modified, it is **not overwritten** unless you use `--force`.
+
+---
+
+## 3. Base domain.yaml structure
+
+The `domain.yaml` file supports three top-level sections besides `aggregates:`:
+
+| Root section | Purpose |
+|--------------|---------|
+| `aggregates:` | Domain model: entities, value objects, enums, events |
+| `listeners:` | Integration events this module **consumes** (async, Kafka) |
+| `ports:` | HTTP services this module **calls** outbound (sync, Feign) |
+| `endpoints:` | REST endpoints this module **exposes** (declarative controller generation) |
+
+```yaml
+aggregates:                          # List of aggregates in the module
+  - name: Order                      # Aggregate name (PascalCase)
+    entities:                        # Entities of the aggregate
+      - name: Order                  # Entity name (PascalCase)
+        isRoot: true                 # true = aggregate root
+        tableName: orders            # SQL table name (optional)
+        audit:                       # Auditing (optional)
+          enabled: true
+          trackUser: false
+        fields:                      # Entity fields
+          - name: id
+            type: String
+          - name: status
+            type: OrderStatus        # Reference to enum or VO
+        relationships:               # JPA relationships (optional)
+          - type: OneToMany
+            target: OrderItem
+            mappedBy: order
+            cascade: [PERSIST, MERGE, REMOVE]
+            fetch: LAZY
+
+      - name: OrderItem              # Secondary entity (no isRoot or isRoot: false)
+        tableName: order_items
+        fields:
+          - name: id
+            type: Long
+          - name: quantity
+            type: Integer
+
+    valueObjects:                    # Aggregate Value Objects
+      - name: Money
+        fields:
+          - name: amount
+            type: BigDecimal
+          - name: currency
+            type: String
+
+    enums:                           # Aggregate enums
+      - name: OrderStatus
+        values: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
+
+    events:                          # Domain events (optional)
+      - name: OrderPlaced
+        fields:
+          - name: customerId
+            type: String
+```
+
+> **Supported synonyms**: `fields` = `properties`; `target` = `targetEntity`
+
+### The `id` field rule
+
+Every entity **must** have a field named exactly `id`:
+
+| `id` type | Generated strategy |
+|-----------|--------------------|
+| `String` | `@GeneratedValue(strategy = GenerationType.UUID)` |
+| `Long` | `@GeneratedValue(strategy = GenerationType.IDENTITY)` |
+
+---
+
+## 4. Supported data types
+
+| YAML type | Java type | Notes |
+|-----------|-----------|-------|
+| `String` | `String` | For `id` generates UUID |
+| `Integer` | `Integer` | For `id` generates IDENTITY |
+| `Long` | `Long` | For `id` generates IDENTITY |
+| `Double` | `Double` | |
+| `BigDecimal` | `BigDecimal` | |
+| `Boolean` | `Boolean` | |
+| `LocalDate` | `LocalDate` | Auto-imported |
+| `LocalDateTime` | `LocalDateTime` | Auto-imported |
+| `LocalTime` | `LocalTime` | Auto-imported |
+| `UUID` | `UUID` | Auto-imported |
+| `List<String>` | `List<String>` | `@ElementCollection` |
+| `List<VO>` | `List<VoJpa>` | `@ElementCollection` |
+| Enum name | Module enum | `@Enumerated(STRING)` |
+| VO name | Value Object | `@Embedded` |
+
+---
+
+## 5. Field properties
+
+```yaml
+fields:
+  - name: fieldName        # camelCase, required
+    type: String           # Java type, required
+    readOnly: false        # default false
+    hidden: false          # default false
+    defaultValue: null     # only meaningful when readOnly: true
+    validations: []        # JSR-303 annotations
+    annotations: []        # raw JPA annotations
+    reference:             # semantic reference to another aggregate
+      aggregate: Customer
+      module: customers
+    enumValues: []         # inline enum (alternative to enums:)
+```
+
+### Visibility matrix
+
+| Field | Creation constructor | CreateDto/Command | Full constructor | ResponseDto |
+|-------|---------------------|-------------------|------------------|-------------|
+| normal | ✅ | ✅ | ✅ | ✅ |
+| `readOnly: true` | ❌ | ❌ | ✅ | ✅ |
+| `hidden: true` | ✅ | ✅ | ✅ | ❌ |
+| `readOnly + hidden` | ❌ | ❌ | ✅ | ❌ |
+
+### readOnly
+
+Marks a field as calculated/derived: excluded from the business constructor and `CreateDto`/`CreateCommand`, but present in the full constructor (reconstruction from persistence) and in `ResponseDto`.
+
+```yaml
+fields:
+  - name: totalAmount
+    type: BigDecimal
+    readOnly: true    # calculated from the sum of items
+```
+
+> When an enum has `initialValue`, the corresponding field is automatically treated as `readOnly`.
+
+### defaultValue
+
+Assigns an initial value to a `readOnly` field in the creation constructor. The generator emits the assignment in the business constructor and `@Builder.Default` in the JPA entity. Ignored (with a warning) on non-readOnly fields.
+
+```yaml
+fields:
+  - name: totalAmount
+    type: BigDecimal
+    readOnly: true
+    defaultValue: "0.00"      # → new BigDecimal("0.00")
+
+  - name: status
+    type: OrderStatus
+    readOnly: true
+    defaultValue: PENDING      # → OrderStatus.PENDING
+
+  - name: itemCount
+    type: Integer
+    readOnly: true
+    defaultValue: 0            # → 0
+```
+
+Generated in the business constructor:
+
+```java
+public Order(String customerId) {
+    this.customerId = customerId;
+    this.totalAmount = new BigDecimal("0.00");  // ← defaultValue
+    this.status = OrderStatus.PENDING;           // ← defaultValue
+    this.itemCount = 0;                          // ← defaultValue
+}
+```
+
+Generated in the JPA entity:
+
+```java
+@Builder.Default
+private BigDecimal totalAmount = new BigDecimal("0.00");
+
+@Enumerated(EnumType.STRING)
+@Builder.Default
+private OrderStatus status = OrderStatus.PENDING;
+```
+
+### hidden
+
+Marks a field as sensitive: included on creation but does NOT appear in `ResponseDto`.
+
+```yaml
+fields:
+  - name: passwordHash
+    type: String
+    hidden: true    # do not expose in API
+```
+
+### annotations (raw JPA)
+
+Allows adding custom JPA annotations to the generated JPA entity.
+
+```yaml
+fields:
+  - name: email
+    type: String
+    annotations:
+      - "@Column(unique = true, nullable = false)"
+```
+
+### reference
+
+Declares a semantic reference to a field in another aggregate. Generates a Javadoc comment indicating the relationship, without creating a code dependency.
+
+```yaml
+fields:
+  - name: customerId
+    type: String
+    reference:
+      aggregate: Customer
+      module: customers
+```
+
+Generated in the domain entity:
+
+```java
+/** @see customers.Customer */
+private String customerId;
+```
+
+---
+
+## 6. JSR-303 Validations
+
+Validations are declared on the field and applied to `CreateCommand` and `CreateDto`. They are **not** added to domain entities.
+
+```yaml
+fields:
+  - name: name
+    type: String
+    validations:
+      - type: NotBlank
+        message: "Name is required"
+      - type: Size
+        min: 2
+        max: 100
+```
+
+Auto-generates import: `import jakarta.validation.constraints.*;`
+
+### Supported parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `type` | Annotation name without `@` (required) |
+| `message` | Custom error message |
+| `value` | Single value (for `@Min`, `@Max`) |
+| `min` | Minimum value (for `@Size`, `@DecimalMin`) |
+| `max` | Maximum value (for `@Size`, `@DecimalMax`) |
+| `regexp` | Regular expression (for `@Pattern`) |
+| `integer` | Integer digits (for `@Digits`) |
+| `fraction` | Decimal digits (for `@Digits`) |
+| `inclusive` | Inclusive boundary (for `@DecimalMin`, `@DecimalMax`) |
+
+### Examples by type
+
+```yaml
+# @NotBlank
+- type: NotBlank
+  message: "Field is required"
+
+# @NotNull
+- type: NotNull
+
+# @Size
+- type: Size
+  min: 2
+  max: 255
+
+# @Email
+- type: Email
+
+# @Min / @Max (for numeric fields)
+- type: Min
+  value: 1
+- type: Max
+  value: 999
+
+# @Pattern
+- type: Pattern
+  regexp: "^[A-Z]{2}[0-9]{6}$"
+  message: "Invalid format"
+
+# @DecimalMin / @DecimalMax
+- type: DecimalMin
+  min: "0.01"
+  inclusive: true
+- type: DecimalMax
+  max: "9999.99"
+
+# @Digits
+- type: Digits
+  integer: 6
+  fraction: 2
+```
+
+---
+
+## 7. Auditing
+
+### Syntax
+
+```yaml
+# New (recommended)
+audit:
+  enabled: true       # adds createdAt, updatedAt
+  trackUser: true     # also adds createdBy, updatedBy
+
+# Legacy (equivalent to audit.enabled: true, trackUser: false)
+auditable: true
+```
+
+### Generated JPA inheritance
+
+| Configuration | JPA base class |
+|---------------|----------------|
+| No auditing | no inheritance |
+| `audit.enabled: true` | `extends AuditableEntity` |
+| `audit.trackUser: true` | `extends FullAuditableEntity` |
+
+### Generated fields
+
+| Field | `audit.enabled` | `audit.trackUser` | In ResponseDto |
+|-------|-----------------|-------------------|----------------|
+| `createdAt` | ✅ | ✅ | ✅ |
+| `updatedAt` | ✅ | ✅ | ✅ |
+| `createdBy` | ❌ | ✅ | ❌ |
+| `updatedBy` | ❌ | ✅ | ❌ |
+
+> `createdBy` and `updatedBy` are administrative metadata: they are never exposed in response DTOs.
+
+### Infrastructure generated with `trackUser: true`
+
+When `trackUser` is enabled, eva4j automatically generates:
+
+| File | Purpose |
+|------|---------|
+| `UserContextHolder.java` | ThreadLocal for the current user |
+| `UserContextFilter.java` | Captures the `X-User` header from each request |
+| `AuditorAwareImpl.java` | Provides the current user to JPA Auditing |
+
+`Application.java` is configured with `@EnableJpaAuditing(auditorAwareRef = "auditorProvider")`.
+
+### Example
+
+```yaml
+entities:
+  - name: Order
+    isRoot: true
+    tableName: orders
+    audit:
+      enabled: true
+      trackUser: true
+    fields:
+      - name: id
+        type: String
+      - name: amount
+        type: BigDecimal
+```
+
+> Audit fields **must not be defined manually** in `fields:`; they are inherited from the JPA base class.
+
+---
+
+## 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
+
+| Property | Values | Description |
+|----------|--------|-------------|
+| `type` | `OneToMany`, `ManyToOne`, `OneToOne`, `ManyToMany` | Relationship type |
+| `target` / `targetEntity` | Entity name | Related entity |
+| `mappedBy` | field name | Inverse side of the relationship |
+| `joinColumn` | column name | FK column name |
+| `cascade` | array of `PERSIST`, `MERGE`, `REMOVE`, `REFRESH`, `DETACH`, `ALL` | Cascade operations |
+| `fetch` | `LAZY` (default), `EAGER` | Loading strategy |
+
+### Automatic inverse side generation
+
+When you define `OneToMany` with `mappedBy`, eva4j automatically generates `@ManyToOne` in the target JPA entity. **Defining both sides is not required.**
+
+```yaml
+# ✅ Only this is needed
+entities:
+  - name: Order
+    isRoot: true
+    relationships:
+      - type: OneToMany
+        target: OrderItem
+        mappedBy: order
+        cascade: [PERSIST, MERGE, REMOVE]
+        fetch: LAZY
+
+# eva4j generates in OrderItemJpa:
+# @ManyToOne(fetch = FetchType.LAZY)
+# @JoinColumn(name = "order_id")
+# private OrderJpa order;
+```
+
+> If you define `ManyToOne` manually, that definition takes priority over auto-generation.
+
+### OneToMany
+
+```yaml
+relationships:
+  - type: OneToMany
+    target: OrderItem
+    mappedBy: order
+    cascade: [PERSIST, MERGE, REMOVE]
+    fetch: LAZY
+```
+
+Generated in domain:
+
+```java
+private List<OrderItem> orderItems = new ArrayList<>();
+public void addOrderItem(OrderItem item) { orderItems.add(item); }
+public void removeOrderItem(OrderItem item) { orderItems.remove(item); }
+```
+
+### ManyToOne (manual, when you need a specific FK)
+
+```yaml
+relationships:
+  - type: ManyToOne
+    target: Order
+    joinColumn: fk_order_uuid
+    fetch: LAZY
+```
+
+### OneToOne
+
+```yaml
+# Inverse side (with mappedBy)
+relationships:
+  - type: OneToOne
+    target: OrderSummary
+    mappedBy: order
+    cascade: [PERSIST, MERGE]
+    fetch: LAZY
+
+# Owner side (with FK)
+relationships:
+  - type: OneToOne
+    target: Order
+    joinColumn: order_id
+    fetch: LAZY
+```
+
+### When to define ManyToOne manually
+
+| Scenario | Define ManyToOne? |
+|----------|------------------|
+| Standard relationship with `mappedBy` | ❌ eva4j generates it |
+| FK with custom name | ✅ Yes, to control `joinColumn` |
+| Multiple FKs to the same entity | ✅ Yes, for distinct names |
+| Unidirectional relationship (no inverse) | ✅ Yes |
+
+### Recommended cascade
+
+```yaml
+# Child has no meaning without parent → include REMOVE
+cascade: [PERSIST, MERGE, REMOVE]
+
+# Child has an independent lifecycle
+cascade: [PERSIST, MERGE]
+```
+
+---
+
+## 9. Value Objects
+
+Immutable objects that represent domain concepts without their own identity.
+
+```yaml
+valueObjects:
+  - name: Money
+    fields:
+      - name: amount
+        type: BigDecimal
+      - name: currency
+        type: String
+```
+
+Generates:
+
+- `Money.java` – immutable domain class with constructor, getters, `equals()`, `hashCode()`
+- `MoneyJpa.java` – `@Embeddable` with Lombok
+
+Usage in a field:
+
+```yaml
+- name: totalAmount
+  type: Money    # automatically detected as @Embedded
+```
+
+### Value Objects with business methods
+
+Value Objects can declare methods directly in `domain.yaml`. The generator emits the method body verbatim inside the VO class.
+
+```yaml
+valueObjects:
+  - name: Money
+    fields:
+      - name: amount
+        type: BigDecimal
+      - name: currency
+        type: String
+    methods:
+      - name: add
+        returnType: Money
+        parameters:
+          - name: other
+            type: Money
+        body: "return new Money(this.amount.add(other.getAmount()), this.currency);"
+      - name: isPositive
+        returnType: boolean
+        parameters: []
+        body: "return this.amount.compareTo(BigDecimal.ZERO) > 0;"
+```
+
+Generated in the domain VO:
+
+```java
+public Money add(Money other) {
+    return new Money(this.amount.add(other.getAmount()), this.currency);
+}
+
+public boolean isPositive() {
+    return this.amount.compareTo(BigDecimal.ZERO) > 0;
+}
+```
+
+> Methods are only generated in the domain VO (`Money.java`), **not** in the JPA embeddable (`MoneyJpa.java`).
+
+### List of Value Objects
+
+```yaml
+- name: addresses
+  type: List<Address>
+```
+
+Generates:
+
+```java
+@ElementCollection
+@CollectionTable(name = "entity_addresses", joinColumns = @JoinColumn(name = "entity_id"))
+@Builder.Default
+private List<AddressJpa> addresses = new ArrayList<>();
+```
+
+---
+
+## 10. Enums and state transitions
+
+### Simple enum
+
+```yaml
+enums:
+  - name: OrderStatus
+    values: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
+```
+
+Generates `OrderStatus.java` with the enumerated values. In JPA: `@Enumerated(EnumType.STRING)`.
+
+### Enum with state transitions
+
+Transitions generate business methods in the entity, validation logic in the enum, and prevent invalid states.
+
+```yaml
+enums:
+  - name: OrderStatus
+    initialValue: PENDING          # assigns an initial value; field becomes readOnly
+    values: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
+    transitions:
+      - from: PENDING              # can be a string or [array]
+        to: CONFIRMED
+        method: confirm            # name of the method generated in the entity
+      - from: [PENDING, CONFIRMED]
+        to: CANCELLED
+        method: cancel
+        guard: "this.status == OrderStatus.DELIVERED"  # throws BusinessException if true
+      - from: CONFIRMED
+        to: SHIPPED
+        method: ship
+```
+
+#### What is generated in the Enum
+
+```java
+private static final Map<OrderStatus, List<OrderStatus>> VALID_TRANSITIONS = Map.of(
+    PENDING,   List.of(CONFIRMED, CANCELLED),
+    CONFIRMED, List.of(SHIPPED, CANCELLED),
+    SHIPPED,   List.of(DELIVERED));
+
+public boolean canTransitionTo(OrderStatus next) {
+    return VALID_TRANSITIONS.getOrDefault(this, List.of()).contains(next);
+}
+
+public OrderStatus transitionTo(OrderStatus next) {
+    if (!canTransitionTo(next)) {
+        throw new InvalidStateTransitionException(this, next);
+    }
+    return next;
+}
+```
+
+#### What is generated in the aggregate root
+
+One method per transition, plus `is*()` and `can*()` helpers:
+
+```java
+public void confirm() {
+    this.status = this.status.transitionTo(OrderStatus.CONFIRMED);
+}
+
+public void cancel() {
+    if (this.status == OrderStatus.DELIVERED) {
+        throw new BusinessException("Cannot cancel a delivered order");
+    }
+    this.status = this.status.transitionTo(OrderStatus.CANCELLED);
+}
+
+public boolean isPending() { return this.status == OrderStatus.PENDING; }
+public boolean canConfirm() { return this.status.canTransitionTo(OrderStatus.CONFIRMED); }
+```
+
+### `initialValue`
+
+Assigns a default value to the status field in the creation constructor. The field is automatically marked as `readOnly` (does not appear in `CreateDto`/`CreateCommand`).
+
+```yaml
+enums:
+  - name: OrderStatus
+    initialValue: PENDING
+```
+
+### `guard`
+
+Java condition evaluated in the transition method. If the expression is `true`, a `BusinessException` is thrown.
+
+```yaml
+- from: [PENDING, CONFIRMED]
+  to: CANCELLED
+  method: cancel
+  guard: "this.totalAmount.compareTo(BigDecimal.ZERO) == 0"
+```
+
+---
+
+## 11. Domain events
+
+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.
+
+```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
+        triggers:
+          - place             # transition method name that publishes this event
+        fields:
+          - name: orderId                # declared for cross-module Kafka consumers
+            type: String
+          - name: customerId
+            type: String
+          - name: totalAmount
+            type: BigDecimal
+          - name: placedAt
+            type: LocalDateTime
+      - name: OrderCancelled
+        triggers:
+          - cancel
+        fields:
+          - 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:
+- `OrderPlacedEvent` → `ORDER_PLACED` ✓
+- `OrderCancelled` *(no suffix)* → `ORDER_CANCELLED` ✓
+
+**Why prefer explicit `topic:`:** the consumer's `listeners[].topic` must match the producer's topic exactly. Declaring it explicitly in both places eliminates any risk of mismatch.
+
+If an event has **no `triggers`**, the developer must call `raise()` manually inside the business method.
+
+### Generated files
+
+| File | Description |
+|------|-------------|
+| `shared/domain/DomainEvent.java` | Abstract base class (generated once per project) |
+| `domain/models/events/OrderPlaced.java` | Concrete event extending `DomainEvent` |
+| `domain/models/events/OrderCancelled.java` | Concrete event |
+| `raise()` / `pullDomainEvents()` in the aggregate root | Event infrastructure in the entity |
+| `OrderRepositoryImpl.java` | Calls `eventPublisher.publishEvent()` when saving |
+| `OrderDomainEventHandler.java` | Class with `@TransactionalEventListener` per event |
+
+### Generated event
+
+Fields declared as `{entityName}Id` are excluded from the record — consumers use `getAggregateId()` instead.
+
+```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 aggregateId, String customerId, BigDecimal totalAmount, LocalDateTime placedAt) {
+        super(aggregateId);
+        this.customerId = customerId;
+        this.totalAmount = totalAmount;
+        this.placedAt = placedAt;
+    }
+
+    // getters
+}
+```
+
+### 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 someBusinessAction() {
+        // business logic...
+        raise(new OrderPlaced(this.getId(), this.customerId, this.totalAmount, LocalDateTime.now()));
+    }
+
+    protected void raise(DomainEvent event) {
+        domainEvents.add(event);
+    }
+
+    public List<DomainEvent> pullDomainEvents() {
+        List<DomainEvent> events = new ArrayList<>(domainEvents);
+        domainEvents.clear();
+        return events;
+    }
+}
+```
+
+### 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
+
+A `domain.yaml` can contain multiple aggregates. Each one generates its own set of files.
+
+```yaml
+aggregates:
+  - name: Customer
+    entities:
+      - name: Customer
+        isRoot: true
+        fields:
+          - name: id
+            type: String
+          - name: email
+            type: String
+
+  - name: Product
+    entities:
+      - name: Product
+        isRoot: true
+        fields:
+          - name: id
+            type: String
+          - name: name
+            type: String
+    enums:
+      - name: ProductCategory
+        values: [ELECTRONICS, CLOTHING, FOOD]
+```
+
+> Enums and Value Objects are local to the aggregate where they are defined. If two aggregates need the same VO, it must be declared in each one.
+
+---
+
+## 13. Generated files
+
+For each aggregate, approximately the following files are generated:
+
+| File | Layer | Description |
+|------|-------|-------------|
+| `{Root}.java` | Domain | Aggregate root entity |
+| `{Entity}.java` | Domain | Secondary entities |
+| `{Vo}.java` | Domain | Value Objects |
+| `{Enum}.java` | Domain | Enums (with VALID_TRANSITIONS if transitions exist) |
+| `{Event}.java` | Domain | Domain events (`domain/models/events/`) |
+| `{Root}Repository.java` | Domain | Repository interface (port) |
+| `Create{Root}Command.java` | Application | Create command |
+| `Create{Root}CommandHandler.java` | Application | Command handler |
+| `Get{Root}Query.java` | Application | Get by ID query |
+| `Get{Root}QueryHandler.java` | Application | Query handler |
+| `List{Root}Query.java` | Application | Paginated list query |
+| `List{Root}QueryHandler.java` | Application | List handler |
+| `{Root}ResponseDto.java` | Application | Response DTO |
+| `Create{Root}Dto.java` | Application | Create DTO |
+| `{Root}ApplicationMapper.java` | Application | Mapper Command/DTO ↔ Domain |
+| `{Aggregate}DomainEventHandler.java` | Application | `@TransactionalEventListener` per declared event |
+| `{Event}IntegrationEvent.java` | Application | Integration event record (when broker installed) |
+| `MessageBroker.java` | Application | Broker port interface (created/updated) |
+| `{Root}Jpa.java` | Infrastructure | JPA entity |
+| `{Entity}Jpa.java` | Infrastructure | Secondary JPA entities |
+| `{Vo}Jpa.java` | Infrastructure | JPA Value Objects (`@Embeddable`) |
+| `{Root}Mapper.java` | Infrastructure | Mapper Domain ↔ JPA |
+| `{Root}JpaRepository.java` | Infrastructure | Spring Data repository |
+| `{Root}RepositoryImpl.java` | Infrastructure | Repository implementation |
+| `{Root}Controller.java` | Infrastructure | REST controller |
+| `{Broker}MessageBroker.java` | Infrastructure | Broker adapter (created/updated) |
+
+**Additional files when `listeners:` is declared:**
+
+| File | Layer | Description |
+|------|-------|-------------|
+| `{Event}IntegrationEvent.java` | Application | Typed record for the consumed event payload |
+| `{NestedType}.java` | Application | Auxiliary record for object-typed fields |
+| `{UseCase}Command.java` | Application | Command dispatched from the listener |
+| `{UseCase}CommandHandler.java` | Application | Handler stub — implement business logic here |
+| `{Event}KafkaListener.java` | Infrastructure | `@KafkaListener` that deserializes and dispatches |
+| `kafka.yaml` (all envs) | Infrastructure | Topic registration |
+
+**Additional files when `ports:` is declared:**
+
+| File | Layer | Description |
+|------|-------|-------------|
+| `{ServiceName}.java` | Domain | Port interface (returns domain models) |
+| `{DomainType}.java` | Domain | Domain model per unique type (`domain/models/{service}/`) |
+| `{ServiceName}FeignClient.java` | Infrastructure | Feign client (returns infra DTOs) |
+| `{ServiceName}FeignAdapter.java` | Infrastructure | ACL adapter mapping infra DTO → domain model |
+| `{ServiceName}FeignConfig.java` | Infrastructure | Feign timeouts config |
+| `{Method}Dto.java` | Infrastructure | Infra DTO per method with `fields:` |
+| `{Method}RequestDto.java` | Application | Request DTO per method with `body:` |
+| `{NestedType}.java` | Application | Auxiliary record for `nestedTypes:` |
+| `urls.yaml` (all envs) | Infrastructure | Base URL per service |
+
+### Generated REST endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/{module}/{entity}` | Create |
+| `GET` | `/api/{module}/{entity}/{id}` | Get by ID |
+| `GET` | `/api/{module}/{entity}?page=0&size=20` | Paginated list |
+| `PUT` | `/api/{module}/{entity}/{id}` | Update |
+| `DELETE` | `/api/{module}/{entity}/{id}` | Delete |
+
+---
+
+## 14. Complete examples
+
+### Example 1: Order with transitions and events
+
+```yaml
+aggregates:
+  - name: Order
+    entities:
+      - name: Order
+        isRoot: true
+        tableName: orders
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: customerId
+            type: String
+            reference:
+              aggregate: Customer
+              module: customers
+          - name: status
+            type: OrderStatus
+          - name: totalAmount
+            type: BigDecimal
+            readOnly: true
+        relationships:
+          - type: OneToMany
+            target: OrderItem
+            mappedBy: order
+            cascade: [PERSIST, MERGE, REMOVE]
+            fetch: LAZY
+
+      - name: OrderItem
+        tableName: order_items
+        fields:
+          - name: id
+            type: Long
+          - name: productId
+            type: String
+          - name: quantity
+            type: Integer
+            validations:
+              - type: Min
+                value: 1
+          - name: unitPrice
+            type: BigDecimal
+
+    enums:
+      - name: OrderStatus
+        initialValue: PENDING
+        values: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
+        transitions:
+          - from: PENDING
+            to: CONFIRMED
+            method: confirm
+          - from: CONFIRMED
+            to: SHIPPED
+            method: ship
+          - from: [PENDING, CONFIRMED]
+            to: CANCELLED
+            method: cancel
+            guard: "this.status == OrderStatus.DELIVERED"
+
+    events:
+      - name: OrderPlaced
+        fields:
+          - name: customerId
+            type: String
+      - name: OrderCancelled
+        fields:
+          - name: reason
+            type: String
+```
+
+### Example 2: User with auditing and a sensitive field
+
+```yaml
+aggregates:
+  - name: User
+    entities:
+      - name: User
+        isRoot: true
+        tableName: users
+        audit:
+          enabled: true
+          trackUser: true
+        fields:
+          - name: id
+            type: String
+          - name: username
+            type: String
+            validations:
+              - type: NotBlank
+              - type: Size
+                min: 3
+                max: 50
+          - name: email
+            type: String
+            validations:
+              - type: Email
+            annotations:
+              - "@Column(unique = true)"
+          - name: passwordHash
+            type: String
+            hidden: true
+          - name: role
+            type: UserRole
+          - name: active
+            type: Boolean
+
+    enums:
+      - name: UserRole
+        values: [ADMIN, USER, MODERATOR]
+```
+
+---
+
+## 15. Prerequisites and common errors
+
+### Prerequisites
+
+- Project created with `eva create`
+- Existing module (`eva add module <module>`)
+- `domain.yaml` file at `src/main/java/<package>/<module>/`
+
+### Common errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Module does not exist` | Module was not created | Run `eva add module <module>` |
+| `YAML file not found` | No `domain.yaml` at the expected path | Check `src/main/java/<pkg>/<module>/domain.yaml` |
+| `Invalid relationship target` | Target entity not defined in the same YAML | Define the target entity in the same `domain.yaml` |
+| `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{PluralAggregate}` | **standard** | Proper English plural of aggregate name (via `pluralize` library) | 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{PluralAggregate}By{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{PluralAggregate}`:** The aggregate name is pluralized using the `pluralize` library, which handles English irregular plurals correctly. For example: `Order` → `FindAllOrders`, `Delivery` → `FindAllDeliveries`, `Category` → `FindAllCategories`. Using the wrong plural (e.g. `FindAllDeliverys`) will cause it to 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{PluralAggregate}By{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 + Orders + 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 integration events that this module **consumes** from other modules or external systems. It lives at the **root level** of `domain.yaml`, as a sibling of `aggregates:`.
+
+> **Requires a broker installed:** `eva add kafka-client` — without it, the section is parsed but no files are generated.
+
+### Syntax
+
+```yaml
+# Root level — sibling of aggregates:
+listeners:
+  - event: PaymentApprovedEvent      # PascalCase + suffix Event
+    producer: payments               # Producing module (documentary reference)
+    topic: PAYMENT_APPROVED          # Kafka topic — SCREAMING_SNAKE_CASE, mandatory
+    useCase: ConfirmReservation      # PascalCase use case executed when the event is consumed
+    fields:                          # Payload fields received
+      - name: reservationId
+        type: String
+      - name: approvedAt
+        type: LocalDateTime
+      - name: details                # Object-typed field → declare in nestedTypes:
+        type: PaymentDetails
+    nestedTypes:                     # Auxiliary records for object-typed fields
+      - name: paymentDetails         # camelCase → normalized to PaymentDetails
+        fields:
+          - name: paymentId
+            type: String
+          - name: method
+            type: String
+          - name: amount
+            type: BigDecimal
+```
+
+### Generated files per listener entry
+
+| File | Description |
+|------|-------------|
+| `application/events/{NestedType}.java` | Auxiliary record per `nestedTypes` entry |
+| `application/events/{Event}IntegrationEvent.java` | Typed record with the declared `fields` |
+| `infrastructure/kafkaListener/{Event}KafkaListener.java` | `@KafkaListener` → deserializes and dispatches to `useCase` |
+| `parameters/*/kafka.yaml` | Topic registered under `topics:` |
+| `application/commands/{UseCase}Command.java` | Typed command for the `useCase` |
+| `application/usecases/{UseCase}CommandHandler.java` | Handler stub — implement business logic here |
+
+### Rules
+
+| Property | Convention | Notes |
+|----------|------------|-------|
+| `event:` | PascalCase + suffix `Event` | `PaymentApprovedEvent` ✅ |
+| `topic:` | SCREAMING_SNAKE_CASE | **Mandatory** for standalone modules |
+| `useCase:` | PascalCase, verb + noun | Describes the consumer's action, not the event name |
+| `fields:` | same as entity fields | Defines the typed payload record |
+| `nestedTypes:` | camelCase name, normalized internally | One record per object-typed field |
+
+- `topic:` is **mandatory** when there is no `system.yaml`. When a `system.yaml` exists, it can be inferred from `integrations.async[].topic`, but an explicit value always takes precedence.
+- `nestedTypes:` — declare one entry per object-typed field (not a scalar). The generated record is placed in `application/events/` and used by both the integration event and the command.
+- Verb hints for `useCase`: `Handle`, `Process`, `Confirm`, `Cancel`, `Accumulate`, `Release`, `Notify`, `Update`.
+
+### Example — generated Kafka listener
+
+```java
+@Component("<moduleName>.PaymentApprovedKafkaListener")  // qualified to avoid cross-module collisions
+public class PaymentApprovedKafkaListener {
+
+    private final UseCaseMediator useCaseMediator;
+    private final ObjectMapper objectMapper;
+
+    @Value("${topics.payment-approved}")
+    private String paymentApprovedTopic;
+
+    @KafkaListener(topics = "${topics.payment-approved}")
+    public void handle(EventEnvelope<Map<String, Object>> event, Acknowledgment ack) {
+        String reservationId = objectMapper.convertValue(
+                event.data().get("reservationId"), 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 ConfirmReservationCommand(reservationId, approvedAt, details));
+        ack.acknowledge();
+    }
+}
+```
+
+### Example — generated command handler stub
+
+```java
+@Component
+public class ConfirmReservationCommandHandler
+        implements CommandHandler<ConfirmReservationCommand, Void> {
+
+    @Override
+    @Transactional
+    public Void handle(ConfirmReservationCommand command) {
+        // TODO: implement
+        // 1. Find the reservation by command.reservationId()
+        // 2. Confirm the reservation business rule
+        // 3. Save and return null
+        throw new UnsupportedOperationException("ConfirmReservationCommandHandler not implemented yet");
+    }
+}
+```
+
+### Cross-module listener collision safety
+
+When multiple modules consume the **same** Kafka event, the generator produces listener classes with identical names (e.g. `PaymentApprovedKafkaListener` in both `orders` and `notifications`). This is safe because the generator qualifies each bean with `@Component("<moduleName>.<listenerClassName>")`, preventing `ConflictingBeanDefinitionException`. **No special naming action is required** — unlike `ports[]` where `service:` must be unique per module.
+
+### Contrast: produced vs. consumed events
+
+```
+aggregates:
+  └── events:      → Domain Events this module PRODUCES  (domain/models/events/)
+
+listeners:           → Integration Events this module CONSUMES (infrastructure/kafkaListener/)
+```
+
+---
+
+## 18. HTTP outbound clients (`ports:`)
+
+The `ports:` section declares synchronous HTTP services that this module **calls outbound**. It lives at the **root level** of `domain.yaml`, as a sibling of `aggregates:` and `listeners:`.
+
+Each entry is one method. Entries with the same `service:` are grouped into a single Feign client.
+
+> Uses Spring Cloud OpenFeign. Requires `spring-cloud-starter-openfeign` in the project's dependencies.
+
+### Syntax
+
+```yaml
+# Root level — sibling of aggregates: and listeners:
+ports:
+  - name: findScreeningById          # method name (camelCase) → drives all naming
+    service: ScreeningService        # groups into one FeignClient (PascalCase)
+    target: screenings               # destination module (documentary reference)
+    baseUrl: http://localhost:8081   # declared once per service; stored in urls.yaml
+    http: GET /screenings/{id}       # 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 the interface
+    domainType: Seat                 # override auto-derived domain type name
+    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 → {Method}RequestDto.java
+      - name: amount
+        type: BigDecimal
+      - name: paymentMethod
+        type: PaymentMethodInput     # object type → declare in nestedTypes:
+    nestedTypes:
+      - name: paymentMethodInput
+        fields:
+          - name: type
+            type: String
+          - name: cardToken
+            type: String
+    fields:                          # response fields
+      - name: paymentId
+        type: String
+      - name: status
+        type: String
+
+  - name: cancelPayment
+    service: PaymentGateway
+    target: payment-gateway-external
+    http: DELETE /payments/{id}
+    # fields: omitted → void return
+```
+
+### Generated files per unique `service:`
+
+| File | Description |
+|------|-------------|
+| `domain/repositories/{ServiceName}.java` | Port interface (returns domain models) |
+| `infrastructure/adapters/{service}/{ServiceName}FeignClient.java` | Feign client (returns infra DTOs) |
+| `infrastructure/adapters/{service}/{ServiceName}FeignAdapter.java` | `@Component implements {ServiceName}` — ACL mapper |
+| `infrastructure/adapters/{service}/{ServiceName}FeignConfig.java` | Feign timeout configuration |
+| `parameters/*/urls.yaml` | Base URL registered |
+
+### Generated files per method
+
+| File | Condition |
+|------|-----------|
+| `domain/models/{service}/{DomainType}.java` | When `fields:` present — domain-side abstraction |
+| `infrastructure/adapters/{service}/{Method}Dto.java` | When `fields:` present — infra DTO (external shape) |
+| `application/dtos/{Method}RequestDto.java` | When `body:` present (POST/PUT/PATCH) |
+| `application/dtos/{NestedType}.java` | When `nestedTypes:` declared |
+
+### Rules
+
+| Property | Convention | Notes |
+|----------|------------|-------|
+| `service:` | PascalCase | Groups methods into one FeignClient. **Must be unique across modules** — if multiple modules call the same external service, each must use a context-specific name (e.g. `OrderCustomerService` in `orders`, `DeliveryCustomerService` in `deliveries`) to avoid Spring bean name collisions |
+| `baseUrl:` | URL string | Declare on **first entry** of each `service:` only |
+| `http:` | `VERB /path` | Same format as `exposes:` in `system.yaml` |
+| `returnList:` | boolean | `true` → `List<{DomainType}>` return type (default: `false`) |
+| `domainType:` | PascalCase | Overrides the domain type name auto-derived from the method name |
+| `body:` | list of fields | Only for POST/PUT/PATCH; emits warning and is ignored on GET/DELETE |
+| `nestedTypes:` | list of type defs | Records in `application/dtos/` for object-typed body fields |
+| `fields:` omitted | — | Return type is `void` in both the interface and Feign client |
+
+### ACL pattern
+
+The generator follows the Anti-Corruption Layer (ACL) pattern to isolate the module from the shape of external APIs:
+
+- **Infra DTOs** (external shape) live in `infrastructure/adapters/{service}/` and match the remote API exactly.
+- **Domain models** (internal abstraction) live in `domain/models/{service}/` and reflect what this module's business logic needs.
+- The `FeignAdapter` maps each `InfraDto → DomainModel` inline using private `to{Type}()` methods.
+- If the external API changes shape, **only the adapter needs to change**; domain logic is unaffected.
+
+### Example — generated port interface and adapter
+
+```java
+// domain/repositories/ScreeningService.java
+public interface ScreeningService {
+    Screening findScreeningById(String id);
+    List<Seat> findAvailableSeats(String id);
+}
+
+// infrastructure/adapters/screeningService/ScreeningServiceFeignAdapter.java
+@Component
+public class ScreeningServiceFeignAdapter implements ScreeningService {
+
+    private final ScreeningServiceFeignClient feignClient;
+
+    @Override
+    public Screening findScreeningById(String id) {
+        FindScreeningByIdDto dto = feignClient.findScreeningById(id);
+        return toScreening(dto);
+    }
+
+    @Override
+    public List<Seat> findAvailableSeats(String id) {
+        return feignClient.findAvailableSeats(id)
+                .stream().map(this::toSeat).toList();
+    }
+
+    private Screening toScreening(FindScreeningByIdDto dto) {
+        return new Screening(dto.getId(), dto.getStartTime());
+    }
+
+    private Seat toSeat(FindAvailableSeatDto dto) {
+        return new Seat(dto.getSeatId(), dto.getSeatType());
+    }
+}
+```
+
+### Contrast: async vs. sync
+
+```
+aggregates:
+  └── events:    → Domain Events this module PRODUCES  (async, broker)
+listeners:         → Integration Events this module CONSUMES (async, broker)
+ports:             → HTTP services this module CALLS outbound (sync, Feign)
+```