eva4j 1.0.11 → 1.0.13

package/docs/commands/GENERATE_ENTITIES.md

@@ -1,2215 +1,909 @@
 # Command `generate entities` (alias: `g entities`)
 
-## 📋 Description
+---
+
+## 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)
+
+---
 
-Generates complete domain model from a YAML definition file, including entities, value objects, enums, JPA mappings, repositories, and CRUD operations with CQRS pattern.
+## 1. Description and purpose
 
-## 🎯 Purpose
+`generate entities` is the core command of eva4j. From a `domain.yaml` file, it generates the complete hexagonal architecture for the module:
 
-Automate the creation of domain models with full hexagonal architecture implementation, eliminating repetitive coding and ensuring consistency across all layers (domain, application, infrastructure).
+- **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
 
-## 📝 Syntax
+The generator understands relationships, auditing, field visibility, validations, state transitions, and domain events.
+
+---
+
+## 2. Syntax and YAML location
 
 ```bash
-eva4j generate entities <aggregate-name>
-eva4j g entities <aggregate-name>        # Short alias
+eva generate entities <module>
+eva g entities <module>          # short alias
 ```
 
 ### Parameters
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `aggregate-name` | Yes | Name of the aggregate (must match YAML file name) |
-
-## 📄 YAML File Structure
-
-The command expects a YAML file at `examples/<aggregate-name>.yaml` with the following structure:
-
-```yaml
-module: <module-name>      # Target module for generation
-
-aggregates:
-  - name: <AggregateName>
-    tableName: <table_name>
-    auditable: true|false
-    
-    entities:
-      - name: <EntityName>
-        isRoot: true|false
-        tableName: <table_name>
-        fields:
-          - name: <fieldName>
-            type: <JavaType|ValueObject|Enum>
-            validations:
-              - <@Annotation>
-        relationships:
-          - type: OneToMany|ManyToOne|OneToOne|ManyToMany
-            target: <TargetEntity>
-            mappedBy: <fieldName>       # For inverse side
-            cascade: ALL|PERSIST|MERGE
-            fetch: LAZY|EAGER
-    
-    valueObjects:
-      - name: <ValueObjectName>
-        fields:
-          - name: <fieldName>
-            type: <JavaType>
-    
-    enums:
-      - name: <EnumName>
-        values:
-          - VALUE1
-          - VALUE2
-```
+| `<module>` | Yes | Module name (must already exist in the project) |
 
-## 💡 Examples
+### Options
 
-### Example 1: Simple Customer Aggregate
+| Option | Description |
+|--------|-------------|
+| `--force` | Overwrite files that have developer changes |
 
-**File:** `examples/customer.yaml`
+### YAML location
 
-```yaml
-module: customer
+The file is read from:
 
-aggregates:
-  - name: Customer
-    tableName: customers
-    auditable: true
-    
-    entities:
-      - name: customer
-        isRoot: true
-        fields:
-          - name: id
-            type: Long
-          - name: firstName
-            type: String
-            validations:
-              - "@NotBlank"
-              - "@Size(max = 100)"
-          - name: email
-            type: String
-            validations:
-              - "@Email"
-          - name: status
-            type: CustomerStatus
 ```
-
-**Generate:**
-```bash
-eva4j g entities customer
+src/main/java/<package>/<module>/domain.yaml
 ```
 
-### Example 2: Complex Order with Relations
+> The generator detects developer changes via checksums. If a file was manually modified, it is **not overwritten** unless you use `--force`.
 
-**File:** `examples/order.yaml`
+---
 
-```yaml
-module: order
+## 3. Base domain.yaml structure
 
-aggregates:
-  - name: Order
-    tableName: orders
-    auditable: true
-    
-    entities:
-      - name: order
-        isRoot: true
-        fields:
+```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: Long
-          - name: orderNumber
             type: String
-          - name: totalAmount
-            type: BigDecimal
           - name: status
-            type: OrderStatus
-        relationships:
+            type: OrderStatus        # Reference to enum or VO
+        relationships:               # JPA relationships (optional)
           - type: OneToMany
             target: OrderItem
             mappedBy: order
-            cascade: ALL
+            cascade: [PERSIST, MERGE, REMOVE]
             fetch: LAZY
-      
-      - name: orderItem
-        isRoot: false
+
+      - name: OrderItem              # Secondary entity (no isRoot or isRoot: false)
         tableName: order_items
         fields:
           - name: id
             type: Long
           - name: quantity
             type: Integer
-          - name: unitPrice
+
+    valueObjects:                    # Aggregate Value Objects
+      - name: Money
+        fields:
+          - name: amount
             type: BigDecimal
-        relationships:
-          - type: ManyToOne
-            target: Order
-            fetch: LAZY
-    
-    enums:
+          - name: currency
+            type: String
+
+    enums:                           # Aggregate enums
       - name: OrderStatus
-        values:
-          - PENDING
-          - CONFIRMED
-          - SHIPPED
-          - DELIVERED
-          - CANCELLED
-```
+        values: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
 
-**Generate:**
-```bash
-eva4j g entities order
+    events:                          # Domain events (optional)
+      - name: OrderPlaced
+        fields:
+          - name: customerId
+            type: String
 ```
 
-### Example 3: With Value Objects
+> **Supported synonyms**: `fields` = `properties`; `target` = `targetEntity`
 
-**File:** `examples/evaluation.yaml`
+### The `id` field rule
 
-```yaml
-module: evaluation
+Every entity **must** have a field named exactly `id`:
 
-aggregates:
-  - name: Evaluation
-    tableName: evaluations
-    
-    entities:
-      - name: evaluation
-        isRoot: true
-        fields:
-          - name: id
-            type: String
-          - name: score
-            type: Integer
-        relationships:
-          - type: OneToMany
-            target: EvaluationDoctor
-            cascade: ALL
-      
-      - name: evaluationDoctor
-        isRoot: false
-        fields:
-          - name: id
-            type: Long
-          - name: degrees
-            type: List<Degrees>
-    
-    valueObjects:
-      - name: Degrees
-        fields:
-          - name: title
-            type: String
-          - name: institution
-            type: String
-          - name: year
-            type: Integer
-          - name: typeDegrees
-            type: TypeDegrees
-    
-    enums:
-      - name: TypeDegrees
-        values:
-          - BACHELOR
-          - MASTER
-          - PHD
-```
+| `id` type | Generated strategy |
+|-----------|--------------------|
+| `String` | `@GeneratedValue(strategy = GenerationType.UUID)` |
+| `Long` | `@GeneratedValue(strategy = GenerationType.IDENTITY)` |
 
-**Generate:**
-```bash
-eva4j g entities evaluation
-```
+---
 
-## 📦 Generated Code Structure
+## 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` |
 
-```
-src/main/java/com/example/project/<module>/
-├── domain/
-│   ├── models/
-│   │   ├── Customer.java                    # Domain entity (root)
-│   │   ├── OrderItem.java                   # Domain entity (secondary)
-│   │   ├── valueobjects/
-│   │   │   └── Degrees.java                 # Value object
-│   │   └── enums/
-│   │       └── OrderStatus.java             # Enum
-│   └── repositories/
-│       └── CustomerRepository.java          # Repository port (interface)
-│
-├── application/
-│   ├── commands/
-│   │   ├── CreateCustomerCommand.java       # Create command
-│   │   └── CreateCustomerCommandHandler.java # Command handler
-│   ├── queries/
-│   │   ├── GetCustomerQuery.java            # Get query
-│   │   ├── GetCustomerQueryHandler.java     # Get handler
-│   │   ├── ListCustomersQuery.java          # List query
-│   │   └── ListCustomersQueryHandler.java   # List handler
-│   ├── dtos/
-│   │   ├── CreateCustomerDto.java           # Create DTO
-│   │   ├── CreateOrderItemDto.java          # Nested entity DTO
-│   │   └── CustomerResponseDto.java         # Response DTO
-│   └── mappers/
-│       └── CustomerApplicationMapper.java   # Application mapper (Command/DTO → Domain)
-│
-└── infrastructure/
-    ├── database/
-    │   ├── entities/
-    │   │   ├── CustomerJpa.java             # JPA entity (root)
-    │   │   ├── OrderItemJpa.java            # JPA entity (secondary)
-    │   │   └── valueobjects/
-    │   │       └── DegreesJpa.java          # JPA value object
-    │   ├── repositories/
-    │   │   ├── CustomerJpaRepository.java   # Spring Data repository
-    │   │   └── CustomerRepositoryImpl.java  # Repository implementation
-    │   └── mappers/
-    │       └── CustomerMapper.java          # Infrastructure mapper (Domain ↔ JPA)
-    └── rest/
-        └── controllers/
-            └── CustomerController.java      # REST controller with CRUD endpoints
-```
+---
 
-## ✨ Features
-
-### 1. Domain Layer (Pure Business Logic)
-- ✅ **Entities** - Aggregate root and secondary entities
-- ✅ **Value Objects** - Immutable value types with `@Embedded` support
-- ✅ **Enums** - Type-safe enumerations
-- ✅ **Repository Interfaces** - Ports for persistence
-
-### 2. Application Layer (Use Cases - CQRS)
-- ✅ **Commands** - `CreateCustomerCommand` with validation
-- ✅ **CommandHandlers** - Business logic orchestration
-- ✅ **Queries** - `GetCustomerQuery`, `ListCustomersQuery`
-- ✅ **QueryHandlers** - Read operations with pagination
-- ✅ **DTOs** - Request/Response data transfer objects
-- ✅ **Application Mappers** - Command/DTO → Domain transformations
-
-### 3. Infrastructure Layer (Technical Details)
-- ✅ **JPA Entities** - Persistence annotations (`@Entity`, `@Table`)
-- ✅ **JPA Repositories** - Spring Data JPA implementation
-- ✅ **Infrastructure Mappers** - Domain ↔ JPA bidirectional mapping
-- ✅ **REST Controllers** - CRUD endpoints (`POST`, `GET`, `GET list`)
-
-### 4. Advanced Capabilities
-- ✅ **Relationships** - OneToMany, ManyToOne, OneToOne, ManyToMany
-- ✅ **Nested Entities** - Secondary entities with their own relationships
-- ✅ **Value Object Collections** - `List<ValueObject>` with `@ElementCollection`
-- ✅ **Auditing** - `@CreatedDate`, `@LastModifiedDate` when `auditable: true`
-- ✅ **Cascade Operations** - Configurable cascade types
-- ✅ **Fetch Strategies** - LAZY/EAGER configuration
-- ✅ **Validations** - Bean Validation annotations
-- ✅ **Pagination** - Built-in pagination support for list queries
-
-## 🔄 Supported Relationships
-
-### OneToMany / ManyToOne (Bidirectional)
+## 5. Field properties
 
 ```yaml
-# Parent entity
-entities:
-  - name: order
-    relationships:
-      - type: OneToMany
-        target: OrderItem
-        mappedBy: order      # Field in OrderItem that owns the relationship
-        cascade: ALL
-        fetch: LAZY
+fields:
+  - name: fieldName        # camelCase, required
+    type: String           # Java type, required
+    readOnly: false        # default false
+    hidden: false          # default false
+    validations: []        # JSR-303 annotations
+    annotations: []        # raw JPA annotations
+    reference:             # semantic reference to another aggregate
+      aggregate: Customer
+      module: customers
+    enumValues: []         # inline enum (alternative to enums:)
+```
 
-# Child entity
-  - name: orderItem
-    relationships:
-      - type: ManyToOne
-        target: Order
-        fetch: LAZY
+### 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
 ```
 
-### OneToOne
+> When an enum has `initialValue`, the corresponding field is automatically treated as `readOnly`.
+
+### hidden
+
+Marks a field as sensitive: included on creation but does NOT appear in `ResponseDto`.
 
 ```yaml
-entities:
-  - name: user
-    relationships:
-      - type: OneToOne
-        target: UserProfile
-        cascade: ALL
+fields:
+  - name: passwordHash
+    type: String
+    hidden: true    # do not expose in API
+```
 
-  - name: userProfile
-    relationships:
-      - type: OneToOne
-        target: User
+### 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)"
 ```
 
-### ManyToMany
+### reference
+
+Declares a semantic reference to a field in another aggregate. Generates a Javadoc comment indicating the relationship, without creating a code dependency.
 
 ```yaml
-entities:
-  - name: student
-    relationships:
-      - type: ManyToMany
-        target: Course
-        cascade: PERSIST
+fields:
+  - name: customerId
+    type: String
+    reference:
+      aggregate: Customer
+      module: customers
+```
 
-  - name: course
-    relationships:
-      - type: ManyToMany
-        target: Student
-        mappedBy: courses
+Generated in the domain entity:
+
+```java
+/** @see customers.Customer */
+private String customerId;
 ```
 
-### Relations Between Secondary Entities
+---
 
-```yaml
-entities:
-  - name: evaluationDoctor
-    relationships:
-      - type: OneToMany
-        target: EvaluationBranch      # Another secondary entity
-        cascade: ALL
+## 6. JSR-303 Validations
 
-  - name: evaluationBranch
-    relationships:
-      - type: ManyToOne
-        target: EvaluationDoctor
+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
 ```
 
-## 🎯 Supported Data Types
+Auto-generates import: `import jakarta.validation.constraints.*;`
 
-### Primitive Types
-- `String`, `Integer`, `Long`, `Double`, `Float`, `Boolean`
-- `BigDecimal`, `BigInteger`
-- `LocalDate`, `LocalDateTime`, `LocalTime`
-- `ZonedDateTime`, `Instant`
+### Supported parameters
 
-### Collections
-- `List<ValueObject>` - Generates `@ElementCollection`
-- `List<Entity>` - Generates `@OneToMany`
+| 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`) |
 
-### Custom Types
-- Value Objects (defined in `valueObjects` section)
-- Enums (defined in `enums` section)
+### Examples by type
 
-## 🚀 Next Steps
+```yaml
+# @NotBlank
+- type: NotBlank
+  message: "Field is required"
 
-After generating entities:
+# @NotNull
+- type: NotNull
 
-1. **Review generated code:**
-   ```bash
-   # Check domain models
-   cat src/main/java/com/example/project/<module>/domain/models/*.java
-   ```
+# @Size
+- type: Size
+  min: 2
+  max: 255
 
-2. **Add business logic:**
-   - Edit domain entities to add business methods
-   - Implement domain validations
-   - Add domain events if needed
+# @Email
+- type: Email
 
-3. **Test the API:**
-   ```bash
-   ./gradlew bootRun
-   # POST http://localhost:8080/api/<module>/<entity>
-   # GET  http://localhost:8080/api/<module>/<entity>/{id}
-   # GET  http://localhost:8080/api/<module>/<entity>
-   ```
+# @Min / @Max (for numeric fields)
+- type: Min
+  value: 1
+- type: Max
+  value: 999
 
-4. **Extend functionality:**
-   ```bash
-   eva4j g usecase UpdateCustomer --type command
-   eva4j g usecase DeleteCustomer --type command
-   ```
+# @Pattern
+- type: Pattern
+  regexp: "^[A-Z]{2}[0-9]{6}$"
+  message: "Invalid format"
 
-## ⚠️ Prerequisites
+# @DecimalMin / @DecimalMax
+- type: DecimalMin
+  min: "0.01"
+  inclusive: true
+- type: DecimalMax
+  max: "9999.99"
 
-- Be in a project created with `eva4j create`
-- Module must exist (created with `eva4j add module`)
-- YAML file must exist at `examples/<aggregate-name>.yaml`
+# @Digits
+- type: Digits
+  integer: 6
+  fraction: 2
+```
 
-## 🔍 Validations
+---
 
-The command validates:
-- ✅ Valid eva4j project
-- ✅ Target module exists
-- ✅ YAML file exists and is valid
-- ✅ No syntax errors in YAML
-- ✅ Entity names are unique
-- ✅ Relationship targets exist
-- ✅ Field types are valid
+## 7. Auditing
 
-## 📚 See Also
+### Syntax
 
-- [DOMAIN_YAML_GUIDE.md](../../DOMAIN_YAML_GUIDE.md) - Complete YAML syntax reference
-- [add-module](./ADD_MODULE.md) - Create modules
-- [generate-usecase](./GENERATE_USECASE.md) - Add more use cases
+```yaml
+# New (recommended)
+audit:
+  enabled: true       # adds createdAt, updatedAt
+  trackUser: true     # also adds createdBy, updatedBy
 
-## 🐛 Troubleshooting
+# Legacy (equivalent to audit.enabled: true, trackUser: false)
+auditable: true
+```
 
-**Error: "YAML file not found"**
-- Solution: Create `examples/<aggregate-name>.yaml` file first
+### Generated JPA inheritance
 
-**Error: "Module does not exist"**
-- Solution: Run `eva4j add module <module-name>` first
+| Configuration | JPA base class |
+|---------------|----------------|
+| No auditing | no inheritance |
+| `audit.enabled: true` | `extends AuditableEntity` |
+| `audit.trackUser: true` | `extends FullAuditableEntity` |
 
-**Error: "Invalid relationship target"**
-- Solution: Ensure the target entity is defined in the same aggregate
+### Generated fields
 
-**Import errors after generation**
-- Solution: This has been fixed in recent versions. Make sure you're using eva4j 1.0.3+
-- If still happening, check that field types match defined ValueObjects/Enums
+| Field | `audit.enabled` | `audit.trackUser` | In ResponseDto |
+|-------|-----------------|-------------------|----------------|
+| `createdAt` | ✅ | ✅ | ✅ |
+| `updatedAt` | ✅ | ✅ | ✅ |
+| `createdBy` | ❌ | ✅ | ❌ |
+| `updatedBy` | ❌ | ✅ | ❌ |
 
-**Compilation errors with List<ValueObject>**
-- Solution: Updated in latest version to use `List<ValueObjectJpa>` in JPA entities
-  - Mapper name: `OrderMapper.java`
-  - File organization
-  - Generated code references
+> `createdBy` and `updatedBy` are administrative metadata: they are never exposed in response DTOs.
 
----
+### Infrastructure generated with `trackUser: true`
 
-## Entities
+When `trackUser` is enabled, eva4j automatically generates:
 
-### Root Entity (Aggregate Root)
+| 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 |
 
-The root entity is the entry point to the aggregate. All operations must go through it.
+`Application.java` is configured with `@EnableJpaAuditing(auditorAwareRef = "auditorProvider")`.
 
-**⚠️ Important**: The root entity is defined within the `entities` array with `isRoot: true`.
+### Example
 
 ```yaml
-aggregates:
+entities:
   - name: Order
-    entities:
-      - name: order              # Entity name (camelCase or snake_case)
-        isRoot: true             # ← REQUIRED to mark the root
-        tableName: orders        # Table name in DB (optional)
-        
-        fields:
-          - name: id
-            type: String         # String generates UUID, Long generates IDENTITY
-            
-          - name: orderNumber
-            type: String
-            
-          - name: status
-            type: OrderStatus    # Reference to an enum
-            
-          - name: totalAmount
-            type: Money          # Reference to a value object
-            
-          - name: createdAt
-            type: LocalDateTime
-        
-        relationships:
-          - type: OneToMany
-            target: OrderItem
-            mappedBy: order
-            cascade: [PERSIST, MERGE, REMOVE]
-            fetch: LAZY
+    isRoot: true
+    tableName: orders
+    audit:
+      enabled: true
+      trackUser: true
+    fields:
+      - name: id
+        type: String
+      - name: amount
+        type: BigDecimal
 ```
 
-### Secondary Entities
+> Audit fields **must not be defined manually** in `fields:`; they are inherited from the JPA base class.
+
+---
+
+## 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
 
-Entities that belong to the aggregate but are not the root. They are defined in the same `entities` array **without** `isRoot` (or with `isRoot: false`).
+When you define `OneToMany` with `mappedBy`, eva4j automatically generates `@ManyToOne` in the target JPA entity. **Defining both sides is not required.**
 
 ```yaml
-aggregates:
+# ✅ Only this is needed
+entities:
   - name: Order
-    entities:
-      # ... root entity order with isRoot: true ...
-      
-      - name: orderItem          # ← Secondary entity
-        tableName: order_items
-        # Without isRoot or isRoot: false = secondary
-        
-        fields:
-          - name: id
-            type: Long
-            
-          - name: productId
-            type: String
-            
-          - name: quantity
-            type: Integer
-            
-          - name: unitPrice
-            type: Money
-        
-        relationships:
-          - type: ManyToOne
-            target: Order
-            joinColumn: order_id
-            fetch: LAZY
+    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;
 ```
 
-### Fields
+> If you define `ManyToOne` manually, that definition takes priority over auto-generation.
 
-#### Syntax
+### OneToMany
 
 ```yaml
-fields:
-  - name: fieldName          # Field name (camelCase) - REQUIRED
-    type: String             # Java data type - REQUIRED
+relationships:
+  - type: OneToMany
+    target: OrderItem
+    mappedBy: order
+    cascade: [PERSIST, MERGE, REMOVE]
+    fetch: LAZY
 ```
 
-**Supported properties:**
-- `name`: Field name (required)
-- `type`: Java data type (required)
+Generated in domain:
 
-#### Automatic Type Detection
+```java
+private List<OrderItem> orderItems = new ArrayList<>();
+public void addOrderItem(OrderItem item) { orderItems.add(item); }
+public void removeOrderItem(OrderItem item) { orderItems.remove(item); }
+```
 
-eva4j automatically detects field types based **only** on `type`:
+### ManyToOne (manual, when you need a specific FK)
 
-**✅ Value Objects** - Automatically detected
 ```yaml
-fields:
-  - name: totalAmount
-    type: Money        # If Money is in valueObjects → automatic @Embedded
+relationships:
+  - type: ManyToOne
+    target: Order
+    joinColumn: fk_order_uuid
+    fetch: LAZY
 ```
 
-**✅ Enums** - Automatically detected
-```yaml
-fields:
-  - name: status
-    type: OrderStatus  # If OrderStatus is in enums → @Enumerated(STRING)
-```
+### OneToOne
 
-**✅ Primitive types**
 ```yaml
-fields:
-  - name: name
-    type: String       # → VARCHAR
-  - name: age
-    type: Integer      # → INTEGER
-  - name: price
-    type: BigDecimal   # → DECIMAL
-```
+# Inverse side (with mappedBy)
+relationships:
+  - type: OneToOne
+    target: OrderSummary
+    mappedBy: order
+    cascade: [PERSIST, MERGE]
+    fetch: LAZY
 
-**✅ Date types** - Automatically imported
-```yaml
-fields:
-  - name: createdAt
-    type: LocalDateTime  # → timestamp + import java.time.LocalDateTime
+# Owner side (with FK)
+relationships:
+  - type: OneToOne
+    target: Order
+    joinColumn: order_id
+    fetch: LAZY
 ```
 
-**✅ Collections** - Automatic @ElementCollection
+### 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
-fields:
-  - name: tags
-    type: List<String>   # → @ElementCollection with secondary table
-```
+# Child has no meaning without parent → include REMOVE
+cascade: [PERSIST, MERGE, REMOVE]
 
-#### ❌ NO need to specify
+# Child has an independent lifecycle
+cascade: [PERSIST, MERGE]
+```
 
-eva4j automatically generates the correct JPA annotations:
-- `@Embedded` for Value Objects
-- `@Enumerated(EnumType.STRING)` for Enums
-- `@ElementCollection` for lists
-- Required imports
+---
 
-#### ⚠️ MANDATORY RULE: `id` Field
+## 9. Value Objects
 
-**All entities MUST have a field named exactly `id`.**
+Immutable objects that represent domain concepts without their own identity.
 
 ```yaml
-# ✅ CORRECT - All entities have 'id'
-entities:
-  - name: order
-    isRoot: true
-    fields:
-      - name: id          # ← REQUIRED
-        type: String      # String = UUID, Long = IDENTITY
-      - name: orderNumber
-        type: String
-  
-  - name: orderItem
+valueObjects:
+  - name: Money
     fields:
-      - name: id          # ← REQUIRED also in secondary entities
-        type: Long
-      - name: productId
+      - name: amount
+        type: BigDecimal
+      - name: currency
         type: String
 ```
 
-**Reasons:**
-- ✅ JPA requires `@Id` in all entities
-- ✅ Eva4j automatically generates `@Id` and `@GeneratedValue` for the `id` field
-- ✅ Clear and consistent convention across the domain
+Generates:
 
-**Supported types for `id`:**
-- `String` → Generates `@GeneratedValue(strategy = GenerationType.UUID)`
-- `Long` → Generates `@GeneratedValue(strategy = GenerationType.IDENTITY)`
+- `Money.java` – immutable domain class with constructor, getters, `equals()`, `hashCode()`
+- `MoneyJpa.java` – `@Embeddable` with Lombok
 
-**❌ INCORRECT:**
-```yaml
-# ❌ Without 'id' field - Application will fail
-fields:
-  - name: orderNumber
-    type: String
-  # ← Missing 'id' field
+Usage in a field:
 
-# ❌ Different name - Won't work
-fields:
-  - name: orderId     # ← Must be named exactly 'id'
-    type: String
+```yaml
+- name: totalAmount
+  type: Money    # automatically detected as @Embedded
 ```
 
-**💡 Business Identifiers:**
-
-If you need a business identifier in addition to the technical ID:
+### List of Value Objects
 
 ```yaml
-fields:
-  - name: id              # ← Technical ID (required)
-    type: String
-  - name: orderNumber     # ← Business ID (optional)
-    type: String
-  - name: invoiceNumber   # ← Another business identifier
-    type: String
-```
-
----
-
-#### Correct Examples
-
-```yaml
-# Value Object
-fields:
-  - name: totalAmount
-    type: Money              # ✅ Sufficient - eva4j automatically detects
-
-# Enum
-fields:
-  - name: status
-    type: OrderStatus        # ✅ Sufficient - eva4j automatically detects
-
-# Primitive type
-fields:
-  - name: description
-    type: String             # ✅ Basic type
-
-# Collection
-fields:
-  - name: tags
-    type: List<String>       # ✅ Automatic @ElementCollection
-```
-
----
-
-### Automatic Auditing
-
-eva4j supports automatic entity auditing using the `auditable` property. When set to `true`, the entity will automatically include creation and modification date fields.
-
-#### Syntax
-
-```yaml
-entities:
-  - name: order
-    isRoot: true
-    auditable: true  # ← Activates automatic auditing
-    fields:
-      - name: orderNumber
-        type: String
-```
-
-#### What `auditable: true` Generates
-
-**In the domain entity (`Order.java`):**
-```java
-public class Order {
-    private String orderNumber;
-    private LocalDateTime createdAt;   // ← Automatically added
-    private LocalDateTime updatedAt;   // ← Automatically added
-    
-    // getters/setters automatically generated
-}
-```
-
-**In the JPA entity (`OrderJpa.java`):**
-```java
-@Entity
-@Table(name = "orders")
-public class OrderJpa extends AuditableEntity {  // ← Extends base class
-    @Id
-    @GeneratedValue(strategy = GenerationType.UUID)
-    private String orderNumber;
-    
-    // createdAt/updatedAt fields inherited from AuditableEntity
-}
-```
-
-**Generated base class (`AuditableEntity.java`):**
-```java
-@MappedSuperclass
-@EntityListeners(AuditingEntityListener.class)
-public abstract class AuditableEntity {
-    
-    @CreatedDate
-    @Column(name = "created_at", nullable = false, updatable = false)
-    private LocalDateTime createdAt;
-    
-    @LastModifiedDate
-    @Column(name = "updated_at", nullable = false)
-    private LocalDateTime updatedAt;
-    
-    // getters/setters
-}
-```
-
-#### Features
-
-✅ **Fully automatic**: Timestamps update without additional code  
-✅ **Entity level**: Can be enabled for specific entities  
-✅ **Spring Data JPA**: Uses `@CreatedDate` and `@LastModifiedDate`  
-✅ **Mapper included**: Audit fields are automatically mapped between domain and JPA  
-
-#### Required Configuration
-
-The Spring Boot application already has JPA auditing enabled in the main class:
-
-```java
-@SpringBootApplication
-@EnableJpaAuditing  // ← Already configured by eva4j
-public class Application {
-    public static void main(String[] args) {
-        SpringApplication.run(Application.class, args);
-    }
-}
-```
-
-#### Complete Example
-
-```yaml
-aggregates:
-  - name: Product
-    entities:
-      - name: product
-        isRoot: true
-        auditable: true  # ← Enables auditing
-        fields:
-          - name: productId
-            type: String
-          - name: name
-            type: String
-          - name: price
-            type: BigDecimal
-          # createdAt and updatedAt are automatically added
-      
-      - name: review
-        auditable: true  # ← Secondary entities can also have auditing
-        fields:
-          - name: reviewId
-            type: Long
-          - name: comment
-            type: String
-        relationships:
-          - type: ManyToOne
-            target: product
-            fetch: LAZY
-            joinColumn: product_id
-```
-
-**Resultado en la tabla:**
-```sql
-CREATE TABLE products (
-    product_id VARCHAR(36) PRIMARY KEY,
-    name VARCHAR(255),
-    price DECIMAL(19,2),
-    created_at TIMESTAMP NOT NULL,  -- ← Automático
-    updated_at TIMESTAMP NOT NULL   -- ← Automático
-);
-
-CREATE TABLE reviews (
-    review_id BIGINT PRIMARY KEY AUTO_INCREMENT,
-    comment TEXT,
-    product_id VARCHAR(36),
-    created_at TIMESTAMP NOT NULL,  -- ← Automático
-    updated_at TIMESTAMP NOT NULL,  -- ← Automático
-    FOREIGN KEY (product_id) REFERENCES products(product_id)
-);
-```
-
-#### Notas importantes
-
-- ✅ `auditable` es **opcional** - por defecto es `false`
-- ✅ Puede usarse en **entidad raíz** o **entidades secundarias**
-- ✅ Los campos `createdAt` y `updatedAt` **no deben** definirse manualmente en `fields`
-- ✅ El tipo es siempre `LocalDateTime`
-- ❌ **No incluye** auditoría de usuario (createdBy/updatedBy) - ver [FUTURE_FEATURES.md](FUTURE_FEATURES.md) para esa funcionalidad
-
----
-
-## Value Objects
-
-Los Value Objects son objetos inmutables que representan conceptos del dominio sin identidad propia.
-
-### Definición básica
-
-```yaml
-valueObjects:
-  - name: Money
-    fields:
-      - name: amount
-        type: BigDecimal
-      
-      - name: currency
-        type: String
-```
-
-### Generated Value Object (Domain)
-
-```java
-public class Money {
-    private final BigDecimal amount;
-    private final String currency;
-    
-    public Money(BigDecimal amount, String currency) {
-        this.amount = amount;
-        this.currency = currency;
-    }
-    
-    // Getters
-    public BigDecimal getAmount() { return amount; }
-    public String getCurrency() { return currency; }
-    
-    // equals() and hashCode() based on all fields
-}
-```
-
-### Value Object JPA (@Embeddable)
-
-```java
-@Embeddable
-public class MoneyJpa {
-    private BigDecimal amount;
-    private String currency;
-    
-    // Constructor, getters, setters (Lombok)
-}
-```
-
-### Usage in Entities
-
-```yaml
-fields:
-  - name: totalAmount
-    type: Money        # Automatically detected as VO
-```
-
-Generates in JPA:
-```java
-@Embedded
-private MoneyJpa totalAmount;
-```
-
-### Example: Complex Value Object
-
-```yaml
-valueObjects:
-  - name: Address
-    fields:
-      - name: street
-        type: String
-      
-      - name: city
-        type: String
-      
-      - name: state
-        type: String
-      
-      - name: zipCode
-        type: String
-      
-      - name: country
-        type: String
-```
-
----
-
-## Enums
-
-### Definition
-
-```yaml
-enums:
-  - name: OrderStatus
-    values:
-      - PENDING
-      - CONFIRMED
-      - SHIPPED
-      - DELIVERED
-      - CANCELLED
-```
-
-### Generated Enum
-
-```java
-package com.example.myapp.order.domain.models.enums;
-
-public enum OrderStatus {
-    PENDING,
-    CONFIRMED,
-    SHIPPED,
-    DELIVERED,
-    CANCELLED
-}
-```
-
-### Uso en entidades
-
-```yaml
-fields:
-  - name: status
-    type: OrderStatus  # Se detecta y se importa automáticamente
-```
-
-Genera en JPA:
-```java
-@Enumerated(EnumType.STRING)
-private OrderStatus status;
-```
-
-### Múltiples enums
-
-```yaml
-enums:
-  - name: OrderStatus
-    values: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
-  
-  - name: PaymentMethod
-    values: [CREDIT_CARD, DEBIT_CARD, CASH, BANK_TRANSFER]
-  
-  - name: ShippingMethod
-    values: [STANDARD, EXPRESS, OVERNIGHT]
-```
-
----
-
-## Relaciones
-
-eva4j soporta relaciones JPA bidireccionales completas con generación automática del lado inverso.
-
-### 🎯 Relaciones Bidireccionales Automáticas
-
-**Característica clave**: Cuando defines una relación OneToMany con `mappedBy`, eva4j genera AUTOMÁTICAMENTE la relación inversa ManyToOne en la entidad target.
-
-**Solo necesitas definir UN lado:**
-
-```yaml
-entities:
-  - name: order
-    isRoot: true
-    relationships:
-      - type: OneToMany
-        target: OrderItem
-        mappedBy: order          # ← eva4j crea automáticamente ManyToOne en OrderItem
-        cascade: [PERSIST, MERGE]
-        fetch: LAZY
-```
-
-**eva4j genera automáticamente en OrderItem:**
-
-```java
-// OrderItemJpa.java (automatically generated)
-@ManyToOne(fetch = FetchType.LAZY)
-@JoinColumn(name = "order_id")
-private OrderJpa order;
-```
-
-**Ventajas:**
-- ✅ No necesitas definir ambos lados manualmente
-- ✅ Evita inconsistencias entre relaciones
-- ✅ JPA persiste correctamente la relación bidireccional
-- ✅ Menos código YAML, misma funcionalidad
-
-**Nota**: Si defines manualmente ambos lados en el YAML, la definición manual tiene prioridad sobre la autogeneración.
-
----
-
-### OneToMany (Uno a Muchos)
-
-**Definición en la entidad que tiene la colección:**
-
-```yaml
-entities:
-  - name: order
-    isRoot: true
-    relationships:
-      - type: OneToMany
-        target: OrderItem        # Entidad relacionada
-        mappedBy: order          # Campo en OrderItem que apunta a Order
-        cascade: [PERSIST, MERGE, REMOVE]
-        fetch: LAZY
-```
-
-**Genera en dominio:**
-```java
-private List<OrderItem> orderItems = new ArrayList<>();
-
-public void addOrderItem(OrderItem orderItem) {
-    this.orderItems.add(orderItem);
-}
-
-public void removeOrderItem(OrderItem orderItem) {
-    this.orderItems.remove(orderItem);
-}
-```
-
-**Genera en JPA:**
-```java
-@OneToMany(mappedBy = "order", cascade = {CascadeType.PERSIST, CascadeType.MERGE, CascadeType.REMOVE}, fetch = FetchType.LAZY)
-@Builder.Default
-private List<OrderItemJpa> orderItems = new ArrayList<>();
-```
-
-**Genera automáticamente en OrderItem (lado inverso):**
-```java
-@ManyToOne(fetch = FetchType.LAZY)
-@JoinColumn(name = "order_id")  // Inferido desde mappedBy
-private OrderJpa order;
-```
-
-### ManyToOne (Muchos a Uno)
-
-**Definición manual (opcional si ya usaste mappedBy en OneToMany):**
-
-```yaml
-entities:
-  - name: orderItem
-    # Sin isRoot = entidad secundaria
-    relationships:
-      - type: ManyToOne
-        target: Order
-        joinColumn: order_id   # Columna FK en la tabla
-        fetch: LAZY
-```
-
-**Genera en JPA:**
-```java
-@ManyToOne(fetch = FetchType.LAZY)
-@JoinColumn(name = "order_id")
-private OrderJpa order;
-```
-
-**💡 Tip**: Si ya definiste `OneToMany` con `mappedBy` en Order, NO necesitas definir manualmente el `ManyToOne` en OrderItem. eva4j lo genera automáticamente.
-
----
-
-### ⚠️ REGLA CRÍTICA: Relaciones Bidireccionales
-
-**Para relaciones bidireccionales OneToMany/ManyToOne:**
-
-#### ✅ CORRECTO - Solo definir en la entidad raíz
-
-```yaml
-entities:
-  - name: invoice
-    isRoot: true
-    relationships:
-      - type: OneToMany
-        target: InvoiceItem
-        mappedBy: invoice      # ← Solo esta definición
-        cascade: [PERSIST, MERGE, REMOVE]
-        fetch: LAZY
-  
-  - name: invoiceItem
-    fields:
-      - name: id
-        type: Long
-    # ← SIN relationships definidas
-    # Eva4j genera automáticamente el ManyToOne en InvoiceItemJpa
-```
-
-**Resultado generado:**
-```java
-// InvoiceJpa.java
-@OneToMany(mappedBy = "invoice", cascade = {...})
-private List<InvoiceItemJpa> invoiceItems;
-
-// InvoiceItemJpa.java (automatically generated)
-@ManyToOne(fetch = FetchType.LAZY)
-@JoinColumn(name = "invoice_id")
-private InvoiceJpa invoice;
-```
-
-#### ❌ INCORRECTO - Definir en ambos lados
-
-```yaml
-entities:
-  - name: invoice
-    isRoot: true
-    relationships:
-      - type: OneToMany
-        target: InvoiceItem
-        mappedBy: invoice      # ← Primera definición
-  
-  - name: invoiceItem
-    relationships:
-      - type: ManyToOne        # ← ❌ DUPLICADO - Causará error
-        target: Invoice
-        joinColumn: invoice_id
-```
-
-**Problema:** Genera DOS relaciones `@ManyToOne` en `InvoiceItemJpa`, ambas mapeando a `invoice_id`:
-
-```java
-// InvoiceItemJpa.java (INCORRECTO - Duplicado)
-@ManyToOne
-@JoinColumn(name = "invoice_id")
-private InvoiceJpa invoice;   // ← Del mappedBy
-
-@ManyToOne
-@JoinColumn(name = "invoice_id")
-private InvoiceJpa invoices;  // ← Del ManyToOne explícito
-
-// Error de Hibernate:
-// "Column 'invoice_id' is duplicated in mapping"
-```
-
-#### 📋 Regla de Oro
-
-| Escenario | Definir en Raíz | Definir en Secundaria | Eva4j Genera |
-|-----------|-----------------|----------------------|-------------|
-| **Bidireccional** | `OneToMany` con `mappedBy` | ❌ NADA | `@OneToMany` en raíz + `@ManyToOne` en JPA de secundaria |
-| **Unidireccional** | Opcional | `ManyToOne` con `joinColumn` | Solo lo definido |
-
-#### 💡 Separación Dominio/Persistencia
-
-**Importante:** Eva4j sigue correctamente DDD:
-
-- **Capa de Dominio:** Las entidades secundarias NO tienen referencia a la raíz
-  ```java
-  // InvoiceItem.java (dominio puro)
-  public class InvoiceItem {
-      private Long id;
-      private String description;
-      // ← SIN private Invoice invoice
-  }
-  ```
-
-- **Capa de Persistencia (JPA):** Solo aquí existe la relación
-  ```java
-  // InvoiceItemJpa.java (persistencia)
-  public class InvoiceItemJpa {
-      private Long id;
-      
-      @ManyToOne
-      @JoinColumn(name = "invoice_id")
-      private InvoiceJpa invoice;  // ← Solo en capa JPA
-  }
-  ```
-
-**Ventajas:**
-- ✅ Sin dependencias circulares en dominio
-- ✅ Modelo de dominio más simple
-- ✅ Relación bidireccional solo donde se necesita (persistencia)
-- ✅ Cumple principios de DDD y arquitectura hexagonal
-
----
-
-### OneToOne (Uno a Uno)
-
-**Bidireccional con mappedBy:**
-
-```yaml
-entities:
-  - name: order
-    isRoot: true
-    relationships:
-      - type: OneToOne
-        target: OrderSummary
-        mappedBy: order
-        cascade: [PERSIST, MERGE]
-        fetch: LAZY
-```
-
-**Sin mappedBy (owner):**
-
-```yaml
-entities:
-  - name: orderSummary
-    relationships:
-      - type: OneToOne
-        target: Order
-        joinColumn: order_id
-        fetch: LAZY
-```
-
-### Relationship Options
-
-| Option | Values | Description |
-|--------|--------|-------------|
-| `type` | OneToMany, ManyToOne, OneToOne, ManyToMany | Relationship type |
-| `target` | EntityName | Related entity |
-| `mappedBy` | fieldName | For the inverse side of the relationship |
-| `joinColumn` | column_name | FK column name |
-| `cascade` | [PERSIST, MERGE, REMOVE, REFRESH, DETACH, ALL] | Cascade operations |
-| `fetch` | LAZY, EAGER | Loading strategy |
-
----
-
-### 🔥 Cascade Options (Cascade Operations)
-
-The `cascade` options determine which operations on the parent are automatically propagated to related entities.
-
-#### **⚠️ IMPORTANT: Cascade and Persistence**
-
-If you DON'T define `cascade`, related entities will **NOT be persisted automatically**. This is the most common error:
-
-```yaml
-# ❌ BAD - OrderItems will NOT be saved in DB
-relationships:
-  - type: OneToMany
-    target: OrderItem
-    mappedBy: order
-    cascade: []        # ← Empty array = no cascade
-    fetch: LAZY
-
-# ✅ GOOD - OrderItems are saved automatically with Order
-relationships:
-  - type: OneToMany
-    target: OrderItem
-    mappedBy: order
-    cascade: [PERSIST, MERGE, REMOVE]  # ← Required to persist
-    fetch: LAZY
-```
-
-#### **Cascade Options:**
-
-| Option | Description | When to use? |
-|--------|-------------|--------------|
-| `PERSIST` | When saving the parent, saves new children | ✅ **Always in OneToMany** to create items |
-| `MERGE` | When updating the parent, updates children | ✅ **Always in OneToMany** to edit items |
-| `REMOVE` | When deleting the parent, deletes children | ✅ If children don't make sense without the parent |
-| `REFRESH` | When refreshing the parent, refreshes children | ⚠️ Rarely needed |
-| `DETACH` | When detaching the parent, detaches children | ⚠️ Rarely needed |
-| `ALL` | All of the above operations | ⚠️ Only if you're sure |
-
-#### **Recommended Configurations:**
-
-```yaml
-# 🎯 RECOMMENDED for OneToMany (Order → OrderItem)
-relationships:
-  - type: OneToMany
-    target: OrderItem
-    mappedBy: order
-    cascade: [PERSIST, MERGE, REMOVE]  # ← Creates, updates and deletes items
-    fetch: LAZY
-
-# 🎯 RECOMMENDED for entities with independent lifecycle
-relationships:
-  - type: OneToMany
-    target: OrderItem
-    mappedBy: order
-    cascade: [PERSIST, MERGE]  # ← Without REMOVE, items persist
-    fetch: LAZY
-
-# ⚠️ CAREFUL with ALL - includes REMOVE
-relationships:
-  - type: OneToMany
-    target: OrderItem
-    mappedBy: order
-    cascade: [ALL]  # ← Deleting Order removes all OrderItems
-    fetch: LAZY
-
-# ❌ AVOID empty array if you want to persist children
-relationships:
-  - type: OneToMany
-    target: OrderItem
-    mappedBy: order
-    cascade: []  # ← Requires manually saving OrderItem
-    fetch: LAZY
-```
-
-#### **What happens without Cascade?**
-
-```yaml
-# Without cascade: [PERSIST]
-cascade: []
-
-# Behavior:
-order.addOrderItem(item);
-repository.save(order);  // ❌ Order is saved, OrderItem is NOT
-```
-
-```yaml
-# With cascade: [PERSIST, MERGE]
-cascade: [PERSIST, MERGE]
-
-# Behavior:
-order.addOrderItem(item);
-repository.save(order);  // ✅ Order and OrderItem are saved automatically
-```
-
----
-
-### 🚀 Fetch Options (Loading Strategy)
-
-The `fetch` options determine WHEN related entities are loaded from the database.
-
-#### **Fetch Options:**
-
-| Option | Description | Behavior | When to use? |
-|--------|-------------|----------|--------------|
-| `LAZY` | Load on demand (when accessed) | Only fetches parent initially | ✅ **Recommended by default** |
-| `EAGER` | Immediate load (always) | Fetches parent + children in same query | ⚠️ Only if you ALWAYS need children |
-
-#### **LAZY Example (Recommended):**
-
-```yaml
-relationships:
-  - type: OneToMany
-    target: OrderItem
-    mappedBy: order
-    cascade: [PERSIST, MERGE]
-    fetch: LAZY  # ← Loads items only when accessed
-```
-
-**Generated SQL:**
-```sql
--- First query: Only fetches Order
-SELECT * FROM orders WHERE id = ?
-
--- Second query: Only if you access order.getOrderItems()
-SELECT * FROM order_items WHERE order_id = ?
-```
-
-**✅ Advantages:**
-- Better initial performance
-- Only loads what you need
-- Avoids loading unnecessary data
-
-**⚠️ Disadvantage:**
-- Can cause N+1 queries if you don't use `JOIN FETCH`
-
-#### **Ejemplo EAGER (Usar con cuidado):**
-
-```yaml
-relationships:
-  - type: OneToMany
-    target: OrderItem
-    mappedBy: order
-    cascade: [PERSIST, MERGE]
-    fetch: EAGER  # ← Always loads items with Order
-```
-
-**Generated SQL:**
-```sql
--- Single query: Fetches Order + OrderItems
-SELECT o.*, i.* 
-FROM orders o 
-LEFT JOIN order_items i ON i.order_id = o.id
-WHERE o.id = ?
-```
-
-**✅ Advantage:**
-- Single SQL query
-- Data available immediately
-
-**❌ Disadvantages:**
-- Loads data even if unused
-- Heavier queries
-- Can cause performance issues
-
-#### **Recommended Configurations by Type:**
-
-```yaml
-# OneToMany: ALWAYS LAZY
-relationships:
-  - type: OneToMany
-    target: OrderItem
-    mappedBy: order
-    cascade: [PERSIST, MERGE]
-    fetch: LAZY  # ← Avoids loading all items always
-
-# ManyToOne: LAZY by default, EAGER only if always needed
-relationships:
-  - type: ManyToOne
-    target: Customer
-    joinColumn: customer_id
-    fetch: LAZY  # ← LAZY by default
-
-# OneToOne: LAZY if optional, EAGER if always exists
-relationships:
-  - type: OneToOne
-    target: OrderSummary
-    mappedBy: order
-    cascade: [PERSIST, MERGE]
-    fetch: LAZY  # ← LAZY if not always used
-```
-
-#### **N+1 Problem and how to solve it:**
-
-**Problem:**
-```java
-// With LAZY fetch
-List<Order> orders = orderRepository.findAll();  // 1 query
-orders.forEach(order -> {
-    order.getOrderItems().forEach(item -> {      // N queries (one per Order)
-        System.out.println(item.getProductName());
-    });
-});
-// Total: 1 + N queries = N+1 problem
-```
-
-**Solution - Use JOIN FETCH in queries:**
-```java
-@Query("SELECT o FROM OrderJpa o LEFT JOIN FETCH o.orderItems WHERE o.id = :id")
-OrderJpa findByIdWithItems(@Param("id") String id);
-```
-
----
-
-### When to manually define inverse relationships?
-
-#### ❌ You DON'T need to define ManyToOne if:
-
-You already defined `OneToMany` with `mappedBy` on the "parent" side. eva4j automatically generates the inverse relationship.
-
-**Example - Only define OneToMany:**
-
-```yaml
-# ✅ SUFFICIENT: Only define this in Order
-entities:
-  - name: order
-    isRoot: true
-    relationships:
-      - type: OneToMany
-        target: OrderItem
-        mappedBy: order          # ← eva4j generates ManyToOne automatically
-        cascade: [PERSIST, MERGE, REMOVE]
-        fetch: LAZY
-
-# ❌ DON'T NEED this in OrderItem (generated automatically)
-#   - name: orderItem
-#     relationships:
-#       - type: ManyToOne
-#         target: Order
-#         joinColumn: order_id
-#         fetch: LAZY
-```
-
-**Result:** Complete bidirectional relationship with FK `order_id` generated automatically.
-
-**✅ Advantages:**
-- Less YAML code (only define one side)
-- No duplication or inconsistencies
-- Works the same as defining both sides
-- FK inferred automatically: `{mappedBy}_id`
-
----
-
-#### ✅ You SHOULD define ManyToOne manually if:
-
-##### 1. **You need a specific FK column name**
-
-```yaml
-# Define both sides to control FK name
-entities:
-  - name: order
-    isRoot: true
-    relationships:
-      - type: OneToMany
-        target: OrderItem
-        mappedBy: order
-        cascade: [PERSIST, MERGE]
-        fetch: LAZY
-  
-  - name: orderItem
-    relationships:
-      - type: ManyToOne
-        target: Order
-        joinColumn: fk_pedido_uuid    # ← Custom name
-        fetch: LAZY
-```
-
-**When to use:**
-- Your DB has specific conventions (`fk_*`, prefixes, etc.)
-- Need to maintain compatibility with existing schema
-- Migration from another tool/framework
-
----
-
-##### 2. **Multiple FKs to the same entity**
-
-```yaml
-# Transaction has 'from' and 'to' Account
-entities:
-  - name: transaction
-    tableName: transactions
-    
-    fields:
-      - name: id
-        type: String
-      - name: amount
-        type: BigDecimal
-    
-    relationships:
-      # First relationship
-      - type: ManyToOne
-        target: Account
-        joinColumn: from_account_id    # ← Explicit name required
-        fetch: LAZY
-      
-      # Second relationship to same entity
-      - type: ManyToOne
-        target: Account
-        joinColumn: to_account_id      # ← Different FK name
-        fetch: LAZY
-```
-
-**When to use:**
-- Self-relationships (category tree, org chart)
-- Multiple relationships to same type (from/to, parent/child)
-- Can't use `mappedBy` (which one would it be?)
-
----
-
-##### 3. **Unidirectional relationship (no inverse side)**
-
-```yaml
-# OrderItem needs Product, but Product DOESN'T need OrderItems
-entities:
-  - name: orderItem
-    relationships:
-      - type: ManyToOne
-        target: Product         # Product has NO List<OrderItem>
-        joinColumn: product_id
-        fetch: LAZY
-  
-  # In Product DON'T define OneToMany
-  - name: product
-    isRoot: true
-    fields:
-      - name: id
-        type: String
-      - name: name
-        type: String
-    # No relationships to OrderItem
-```
-
-**When to use:**
-- Performance: avoid loading unnecessary collections
-- Product is not part of Order aggregate
-- Only need navigation in one direction
-
----
-
-#### 📊 Quick Comparison
-
-| Scenario | Define ManyToOne? | Why? |
-|----------|-------------------|------|
-| Standard relationship with `mappedBy` | ❌ No | eva4j generates it automatically |
-| FK with custom name | ✅ Yes | To control `joinColumn` |
-| Multiple FKs to same entity | ✅ Yes | Need explicit names |
-| Unidirectional relationship | ✅ Yes | No inverse side (`mappedBy`) |
-| Specific DB conventions | ✅ Yes | To comply with standards |
-| Simple standard case | ❌ No | Let eva4j generate it |
-
----
-
-#### ⚠️ Error Común
-
-**NO hagas esto:**
-
-```yaml
-# ❌ INCORRECTO: Inconsistencia entre ambos lados
-entities:
-  - name: order
-    isRoot: true
-    relationships:
-      - type: OneToMany
-        target: OrderItem
-        mappedBy: order         # ← Espera campo "order" en OrderItem
-        fetch: LAZY
-  
-  - name: orderItem
-    relationships:
-      - type: ManyToOne
-        target: Order
-        joinColumn: pedido_id  # ← Pero la FK se llama diferente
-        fetch: LAZY
+- name: addresses
+  type: List<Address>
 ```
 
-**Problema:** `mappedBy: order` busca un campo llamado `order`, pero `pedido_id` no coincide con la convención de nombres.
+Generates:
 
-**✅ Soluciones:**
-
-**Opción A - Deja que eva4j genere automáticamente:**
-```yaml
-# Solo define OneToMany, eva4j genera ManyToOne correctamente
-entities:
-  - name: order
-    isRoot: true
-    relationships:
-      - type: OneToMany
-        target: OrderItem
-        mappedBy: order
-        fetch: LAZY
+```java
+@ElementCollection
+@CollectionTable(name = "entity_addresses", joinColumns = @JoinColumn(name = "entity_id"))
+@Builder.Default
+private List<AddressJpa> addresses = new ArrayList<>();
 ```
 
-**Opción B - Define ambos lados consistentemente:**
+---
+
+## 10. Enums and state transitions
+
+### Simple enum
+
 ```yaml
-entities:
-  - name: order
-    isRoot: true
-    relationships:
-      - type: OneToMany
-        target: OrderItem
-        mappedBy: pedido        # ← Coincide con el nombre del campo
-        fetch: LAZY
-  
-  - name: orderItem
-    relationships:
-      - type: ManyToOne
-        target: Order
-        joinColumn: pedido_id
-        fetch: LAZY
+enums:
+  - name: OrderStatus
+    values: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
 ```
 
----
+Generates `OrderStatus.java` with the enumerated values. In JPA: `@Enumerated(EnumType.STRING)`.
 
-#### 💡 Recomendación General
+### Enum with state transitions
 
-**Para el 90% de los casos:**
+Transitions generate business methods in the entity, validation logic in the enum, and prevent invalid states.
 
 ```yaml
-# ✅ MEJOR PRÁCTICA: Solo define OneToMany
-entities:
-  - name: order
-    isRoot: true
-    relationships:
-      - type: OneToMany
-        target: OrderItem
-        mappedBy: order
-        cascade: [PERSIST, MERGE, REMOVE]
-        fetch: LAZY
-
-# NO definas ManyToOne en OrderItem
-# eva4j lo genera automáticamente con:
-# - @JoinColumn(name = "order_id")
-# - @ManyToOne(fetch = FetchType.LAZY)
+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
 ```
 
-**Solo define ambos lados cuando necesites control específico.**
+#### 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));
 
-## Tipos de Datos
+public boolean canTransitionTo(OrderStatus next) {
+    return VALID_TRANSITIONS.getOrDefault(this, List.of()).contains(next);
+}
 
-### Tipos primitivos Java
+public OrderStatus transitionTo(OrderStatus next) {
+    if (!canTransitionTo(next)) {
+        throw new InvalidStateTransitionException(this, next);
+    }
+    return next;
+}
+```
 
-| YAML | Java | JPA | Observaciones |
-|------|------|-----|---------------|
-| `String` | String | VARCHAR | En ID genera UUID |
-| `Integer` | Integer | INTEGER | En ID genera IDENTITY |
-| `Long` | Long | BIGINT | En ID genera IDENTITY |
-| `Double` | Double | DOUBLE | - |
-| `Float` | Float | FLOAT | - |
-| `Boolean` | Boolean | BOOLEAN | - |
-| `BigDecimal` | BigDecimal | DECIMAL | Importa automáticamente |
+#### What is generated in the aggregate root
 
-### Tipos de fecha/hora
+One method per transition, plus `is*()` and `can*()` helpers:
 
-| YAML | Java | Importa automáticamente |
-|------|------|------------------------|
-| `LocalDate` | LocalDate | java.time.LocalDate |
-| `LocalDateTime` | LocalDateTime | java.time.LocalDateTime |
-| `LocalTime` | LocalTime | java.time.LocalTime |
+```java
+public void confirm() {
+    this.status = this.status.transitionTo(OrderStatus.CONFIRMED);
+}
 
-### Tipos especiales
+public void cancel() {
+    if (this.status == OrderStatus.DELIVERED) {
+        throw new BusinessException("Cannot cancel a delivered order");
+    }
+    this.status = this.status.transitionTo(OrderStatus.CANCELLED);
+}
 
-| YAML | Java | Uso |
-|------|------|-----|
-| `UUID` | UUID | IDs únicos |
-| Cualquier Enum | Enum personalizado | Estados, tipos |
-| Cualquier VO | Value Object | Conceptos de dominio |
+public boolean isPending() { return this.status == OrderStatus.PENDING; }
+public boolean canConfirm() { return this.status.canTransitionTo(OrderStatus.CONFIRMED); }
+```
 
-### Colecciones
+### `initialValue`
 
-#### Lista de primitivos
+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
-fields:
-  - name: tags
-    type: List<String>
+enums:
+  - name: OrderStatus
+    initialValue: PENDING
 ```
 
-Genera:
-```java
-@ElementCollection
-@CollectionTable(name = "order_tags", joinColumns = @JoinColumn(name = "order_id"))
-@Column(name = "tags")
-@Builder.Default
-private List<String> tags = new ArrayList<>();
-```
+### `guard`
 
-#### Lista de Value Objects
+Java condition evaluated in the transition method. If the expression is `true`, a `BusinessException` is thrown.
 
 ```yaml
-fields:
-  - name: addresses
-    type: List<Address>  # Address es un VO definido
-```
-
-Genera:
-```java
-@ElementCollection
-@CollectionTable(name = "customer_addresses", joinColumns = @JoinColumn(name = "customer_id"))
-@Builder.Default
-private List<AddressJpa> addresses = new ArrayList<>();
+- from: [PENDING, CONFIRMED]
+  to: CANCELLED
+  method: cancel
+  guard: "this.totalAmount.compareTo(BigDecimal.ZERO) == 0"
 ```
 
 ---
 
-## Ejemplos Completos
+## 11. Domain events
 
-### Ejemplo 1: E-Commerce (Order)
+Events are declared under the aggregate (at the same level as `entities:`, `enums:`, `valueObjects:`).
 
 ```yaml
 aggregates:
   - name: Order
-    entities:
-      - name: order
-        isRoot: true
-        tableName: orders
-        
+    events:
+      - name: OrderPlaced
         fields:
-          - name: id
-            type: String
-          
-          - name: orderNumber
-            type: String
-          
           - name: customerId
             type: String
-          
-          - name: status
-            type: OrderStatus
-          
           - name: totalAmount
-            type: Money
-          
-          - name: shippingAddress
-            type: Address
-          
-          - name: createdAt
-            type: LocalDateTime
-          
-          - name: updatedAt
-            type: LocalDateTime
-        
-        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: productName
-            type: String
-          
-          - name: quantity
-            type: Integer
-          
-          - name: unitPrice
-            type: Money
-          
-          - name: subtotal
-            type: Money
-        
-        relationships:
-          - type: ManyToOne
-            target: Order
-            joinColumn: order_id
-            fetch: LAZY
-    
-    valueObjects:
-      - name: Money
-        fields:
-          - name: amount
             type: BigDecimal
-          - name: currency
-            type: String
-      
-      - name: Address
+      - name: OrderCancelled
         fields:
-          - name: street
-            type: String
-          - name: city
-            type: String
-          - name: state
-            type: String
-          - name: zipCode
+          - name: reason
             type: String
-          - name: country
-            type: String
-    
-    enums:
-      - name: OrderStatus
-        values:
-          - PENDING
-          - CONFIRMED
-          - PROCESSING
-          - SHIPPED
-          - DELIVERED
-          - CANCELLED
-          - REFUNDED
+    entities:
+      - name: Order
+        # ...
+```
+
+### 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
+
+```java
+public final class OrderPlaced extends DomainEvent {
+    private final String customerId;
+    private final BigDecimal totalAmount;
+
+    public OrderPlaced(String customerId, BigDecimal totalAmount) {
+        this.customerId = customerId;
+        this.totalAmount = totalAmount;
+    }
+
+    // getters
+}
+```
+
+### How to raise an event in the entity
+
+```java
+public class Order {
+    private final List<DomainEvent> domainEvents = new ArrayList<>();
+
+    public void place(String customerId, BigDecimal totalAmount) {
+        // business logic...
+        raise(new OrderPlaced(customerId, totalAmount));
+    }
+
+    protected void raise(DomainEvent event) {
+        domainEvents.add(event);
+    }
+
+    public List<DomainEvent> pullDomainEvents() {
+        List<DomainEvent> events = new ArrayList<>(domainEvents);
+        domainEvents.clear();
+        return events;
+    }
+}
 ```
 
-### Ejemplo 2: Blog (Post)
+---
+
+## 12. Multiple aggregates
+
+A `domain.yaml` can contain multiple aggregates. Each one generates its own set of files.
 
 ```yaml
 aggregates:
-  - name: Post
+  - name: Customer
     entities:
-      - name: post
+      - name: Customer
         isRoot: true
-        tableName: posts
-        
         fields:
           - name: id
-            type: Long
-          
-          - name: title
-            type: String
-          
-          - name: slug
             type: String
-          
-          - name: content
-            type: String
-          
-          - name: authorId
+          - name: email
             type: String
-          
-          - name: status
-            type: PostStatus
-          
-          - name: publishedAt
-            type: LocalDateTime
-          
-          - name: tags
-            type: List<String>
-          
-          - name: metadata
-            type: PostMetadata
-        
-        relationships:
-          - type: OneToMany
-            target: Comment
-            mappedBy: post
-            cascade: [PERSIST, MERGE, REMOVE]
-            fetch: LAZY
-      
-      - name: comment
-        tableName: comments
-        
+
+  - name: Product
+    entities:
+      - name: Product
+        isRoot: true
         fields:
           - name: id
-            type: Long
-          
-          - name: authorId
             type: String
-          
-          - name: authorName
-            type: String
-          
-          - name: content
+          - name: name
             type: String
-          
-          - name: createdAt
-            type: LocalDateTime
-          
-          - name: approved
-            type: Boolean
-        
-        relationships:
-          - type: ManyToOne
-            target: Post
-            joinColumn: post_id
-            fetch: LAZY
-    
-    valueObjects:
-      - name: PostMetadata
-        fields:
-          - name: viewCount
-            type: Integer
-          - name: likeCount
-            type: Integer
-          - name: shareCount
-            type: Integer
-    
     enums:
-      - name: PostStatus
-        values: [DRAFT, PUBLISHED, ARCHIVED, DELETED]
+      - name: ProductCategory
+        values: [ELECTRONICS, CLOTHING, FOOD]
 ```
 
-### Ejemplo 3: Banking (Account)
+> 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) |
+| `{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 |
+| `{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 |
+
+### 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: Account
+  - name: Order
     entities:
-      - name: account
+      - name: Order
         isRoot: true
-        tableName: accounts
-        
+        tableName: orders
+        audit:
+          enabled: true
         fields:
           - name: id
             type: String
-          
-          - name: accountNumber
-            type: String
-          
           - name: customerId
             type: String
-          
-          - name: accountType
-            type: AccountType
-          
-          - name: balance
-            type: Money
-          
+            reference:
+              aggregate: Customer
+              module: customers
           - name: status
-            type: AccountStatus
-          
-          - name: openedAt
-            type: LocalDate
-        
+            type: OrderStatus
+          - name: totalAmount
+            type: BigDecimal
+            readOnly: true
         relationships:
           - type: OneToMany
-            target: Transaction
-            mappedBy: account
-            cascade: [PERSIST, MERGE]
+            target: OrderItem
+            mappedBy: order
+            cascade: [PERSIST, MERGE, REMOVE]
             fetch: LAZY
-      
-      - name: transaction
-        tableName: transactions
-        
+
+      - name: OrderItem
+        tableName: order_items
         fields:
           - name: id
+            type: Long
+          - name: productId
             type: String
-          
-          - name: transactionNumber
-            type: String
-          
-          - name: type
-            type: TransactionType
-          
-          - name: amount
-            type: Money
-          
-          - name: description
+          - 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: timestamp
-            type: LocalDateTime
-          
-          - name: balanceAfter
-            type: Money
-        
-        relationships:
-          - type: ManyToOne
-            target: Account
-            joinColumn: account_id
-            fetch: LAZY
-    
-    valueObjects:
-      - name: Money
+      - name: OrderCancelled
         fields:
-          - name: amount
-            type: BigDecimal
-          - name: currency
+          - name: reason
             type: String
-    
-    enums:
-      - name: AccountType
-        values: [CHECKING, SAVINGS, INVESTMENT, CREDIT]
-      
-      - name: AccountStatus
-        values: [ACTIVE, INACTIVE, SUSPENDED, CLOSED]
-      
-      - name: TransactionType
-        values: [DEPOSIT, WITHDRAWAL, TRANSFER, FEE, INTEREST]
 ```
 
-### Ejemplo 4: Múltiples Agregados en un módulo
+### Example 2: User with auditing and a sensitive field
 
 ```yaml
 aggregates:
-  - name: Customer
+  - name: User
     entities:
-      - name: customer
+      - name: User
         isRoot: true
+        tableName: users
+        audit:
+          enabled: true
+          trackUser: true
         fields:
           - name: id
             type: String
-          - name: name
-            type: String
-          - name: email
-            type: String
-          - name: phone
+          - name: username
             type: String
-          - name: registeredAt
-            type: LocalDateTime
-    
-    valueObjects:
-      - name: ContactInfo
-        fields:
+            validations:
+              - type: NotBlank
+              - type: Size
+                min: 3
+                max: 50
           - name: email
             type: String
-          - name: phone
-            type: String
-  
-  - name: Product
-    entities:
-      - name: product
-        isRoot: true
-        fields:
-          - name: id
-            type: String
-          - name: name
-            type: String
-          - name: description
-            type: String
-          - name: price
-            type: Money
-          - name: stock
-            type: Integer
-          - name: category
-            type: ProductCategory
-    
-    valueObjects:
-      - name: Money
-        fields:
-          - name: amount
-            type: BigDecimal
-          - name: currency
-            type: String
-    
-    enums:
-      - name: ProductCategory
-        values: [ELECTRONICS, CLOTHING, FOOD, BOOKS, TOYS]
-```
-
----
-
-## Comando de Generación
-
-```bash
-# Generar todas las entidades del módulo
-eva4j generate entities <module-name>
-```
-
-### Salida generada
+            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]
 ```
-✓ Found 1 aggregate(s) and 1 enum(s)
-
-📦 Aggregates to generate:
-  ├── Order (Root: Order)
-  │   ├── OrderItem
-  │   └── Money (VO)
-
-⠋ Generating files...
-
-✅ Successfully generated 13 files for module 'order'
-
-📁 Generated Files:
-  ✓ Enum: OrderStatus
-  ✓ Domain Entity: Order
-  ✓ JPA Entity: OrderJpa
-  ✓ Domain Entity: OrderItem
-  ✓ JPA Entity: OrderItemJpa
-  ✓ Domain VO: Money
-  ✓ JPA VO: MoneyJpa
-  ✓ Mapper: OrderMapper
-  ✓ Repository: OrderRepository
-  ✓ JPA Repository: OrderJpaRepository
-  ✓ Repository Impl: OrderRepositoryImpl
-```
-
----
-
-## Tips y Mejores Prácticas
-
-### ✅ Hacer
-
-1. **Usa nombres descriptivos**: `orderNumber` en lugar de `number`
-2. **PascalCase para tipos**: `OrderStatus`, `Money`, `Address`
-3. **camelCase para campos**: `totalAmount`, `createdAt`
-4. **snake_case para tablas**: `order_items`, `customer_addresses`
-5. **Define IDs apropiados**: String para UUIDs, Long para secuencias
-6. **Usa Value Objects**: Para conceptos cohesivos (Money, Address)
-7. **Cascade apropiado**: PERSIST, MERGE para agregados; evita ALL
-
-### ❌ Evitar
-
-1. **Don't use Long for UUIDs**: Use String
-2. **Don't create bidirectional relationships without mappedBy**: Define the owner
-3. **Don't use EAGER without reason**: LAZY is better for performance
-4. **Don't mix concepts**: One aggregate = one transaction
-5. **Don't use @Column in domain.yaml**: It's for JPA, generated automatically
-
----
-
-## Current Support and Limitations
-
-### ✅ Supported
-
-- Aggregates with root and secondary entities
-- Embedded Value Objects
-- Enums with values
-- OneToMany, ManyToOne, OneToOne relationships
-- Java primitive and date types
-- Collections of primitives and VOs
-- IDs: String (UUID), Long/Integer (IDENTITY)
-- Custom Cascade and Fetch
-
-### 🚧 Coming Soon
-
-- JSR-303 validations
-- Automatic auditing
-- Soft delete
-- Custom query methods
-- Indexes and constraints
-- Entity inheritance
-
----
-
-## Frequently Asked Questions
-
-**Q: Can I have multiple aggregates in one domain.yaml?**  
-A: Yes, define multiple entries in the `aggregates` array.
-
-**Q: How do I reference an enum from another aggregate?**  
-A: Enums are global to the module, just use the name: `type: OrderStatus`
-
-**Q: Can I use a VO in multiple aggregates?**  
-A: Yes, but you must define it in each aggregate (for now).
-
-**Q: What happens if I regenerate the code?**  
-A: Files are overwritten. Modify only in templates, not in generated code.
-
-**Q: Can I customize generated entities?**  
-A: Yes, modify the templates in `templates/aggregate/`.
 
 ---
 
-## Additional Resources
+## 15. Prerequisites and common errors
 
-- [Implementation Guide](IMPLEMENTATION_SUMMARY.md)
-- [Testing Guide](TESTING_GUIDE.md)
-- [Quick Reference](QUICK_REFERENCE.md)
-- [DDD Documentation](https://martinfowler.com/bliki/DomainDrivenDesign.html)
+### Prerequisites
 
----
+- Project created with `eva create`
+- Existing module (`eva add module <module>`)
+- `domain.yaml` file at `src/main/java/<package>/<module>/`
 
-**Ready to start?** Create your `domain.yaml` and run:
+### Common errors
 
-```bash
-eva4j generate entities <your-module>
-```
+| 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 |