eva4j 1.0.13 → 1.0.15

package/src/commands/generate-http-exchange.js

@@ -307,3 +307,5 @@ async function ensureUrlsImport(projectDir) {
 }
 
 module.exports = generateHttpExchangeCommand;
+module.exports.createOrUpdateUrlsConfig = createOrUpdateUrlsConfig;
+module.exports.ensureUrlsImport = ensureUrlsImport;

package/src/commands/generate-kafka-event.js

@@ -151,7 +151,7 @@ async function generateKafkaEventCommand(moduleName, eventName) {
   try {
     for (const name of eventNames) {
       const normalizedName = toPascalCase(name);
-      const evtClassName = normalizedName.endsWith('Event') ? normalizedName : `${normalizedName}Event`;
+      const evtClassName = normalizedName.endsWith('IntegrationEvent') ? normalizedName : `${normalizedName}IntegrationEvent`;
 
       // In batch mode skip already-existing events; in single mode abort
       const evtPath = path.join(projectDir, 'src', 'main', 'java', packagePath, moduleName, 'application', 'events', `${evtClassName}.java`);
@@ -166,9 +166,9 @@ async function generateKafkaEventCommand(moduleName, eventName) {
         }
       }
 
-      const topicNameKebab = toKebabCase(name);
-      const topicNameCamel = toCamelCase(name);
-      const topicNameSnake = toSnakeCase(name).toUpperCase();
+      const topicNameKebab = toKebabCase(stripEventSuffix(name));
+      const topicNameCamel = toCamelCase(stripEventSuffix(name));
+      const topicNameSnake = toSnakeCase(stripEventSuffix(name)).toUpperCase();
       const topicSpringProperty = `\${topics.${topicNameKebab}}`;
       const selectedDomainEvent = domainEventMap[normalizedName] || null;
 
@@ -218,8 +218,8 @@ async function generateKafkaEventCommand(moduleName, eventName) {
 
     if (!isBatch && generated.length === 1) {
       const r = generated[0];
-      const topicSnake = toSnakeCase(eventNames[0]).toUpperCase();
-      const topicKebab = toKebabCase(eventNames[0]);
+      const topicSnake = toSnakeCase(stripEventSuffix(eventNames[0])).toUpperCase();
+      const topicKebab = toKebabCase(stripEventSuffix(eventNames[0]));
       console.log(chalk.blue('\n✅ Kafka event configured successfully!'));
       console.log(chalk.white(`\n   Event: ${r.name}`));
       console.log(chalk.white(`   Topic: ${topicSnake} (${topicKebab})`));
@@ -393,6 +393,15 @@ async function createOrUpdateKafkaMessageBroker(projectDir, packagePath, context
     // Update existing implementation
     let content = await fs.readFile(adapterPath, 'utf-8');
 
+    // If this is a mock impl (generated by build --mock), replace it wholesale
+    // with the real Kafka implementation before proceeding.
+    const isMockImpl = content.includes('ApplicationEventPublisher') && !content.includes('KafkaTemplate');
+    if (isMockImpl) {
+      const templatePath = path.join(__dirname, '..', '..', 'templates', 'kafka-event', 'KafkaMessageBroker.java.ejs');
+      await renderAndWrite(templatePath, adapterPath, context);
+      return;
+    }
+
     // Check if method already exists
     if (content.includes(methodName)) {
       return; // Method already exists
@@ -566,10 +575,10 @@ async function updateDomainEventHandler(projectDir, packagePath, context) {
     return false;
   }
 
-  // Compute domain event name by stripping 'Event' suffix from eventClassName
-  // e.g. OrderPlacedEvent → OrderPlaced
-  const domainEventName = context.eventClassName.endsWith('Event')
-    ? context.eventClassName.slice(0, -'Event'.length)
+  // Compute domain event name by stripping 'IntegrationEvent' suffix from eventClassName
+  // e.g. OrderPlacedIntegrationEvent → OrderPlaced
+  const domainEventName = context.eventClassName.endsWith('IntegrationEvent')
+    ? context.eventClassName.slice(0, -'IntegrationEvent'.length)
     : context.eventClassName;
 
   // Guard: the TODO comment must exist (generated by g entities)
@@ -606,8 +615,10 @@ async function updateDomainEventHandler(projectDir, packagePath, context) {
   }
 
   // 4. Render the mapping call and replace the TODO block
+  // Derive aggregateName from the handler file name (e.g. BikeDomainEventHandler.java → Bike)
+  const aggregateName = handlerFile.replace('DomainEventHandler.java', '');
   const templatePath = path.join(__dirname, '..', '..', 'templates', 'kafka-event', 'DomainEventHandlerMethod.ejs');
-  const mappingLine = await renderTemplate(templatePath, { ...context, domainEventFields: context.eventFields });
+  const mappingLine = await renderTemplate(templatePath, { ...context, domainEventFields: context.eventFields, aggregateName });
 
   const todoRegex = new RegExp(
     `([ \\t]*\/\/ TODO: handle ${domainEventName}[^\\n]*\\n)(?:[ \\t]*\/\/[^\\n]*\\n)*`
@@ -639,4 +650,80 @@ function injectImportIntoFile(content, importStatement) {
   }
 }
 
+/**
+ * Returns the name of the installed message broker ('kafka' | 'rabbitmq') or null.
+ * Extensibility: add 'rabbitmq' support here when `eva add rabbitmq-client` is implemented.
+ * @param {import('../utils/config-manager')} configManager
+ * @returns {Promise<'kafka'|'rabbitmq'|null>}
+ */
+async function getInstalledBroker(configManager) {
+  if (await configManager.featureExists('kafka')) return 'kafka';
+  if (await configManager.featureExists('rabbitmq')) return 'rabbitmq';
+  return null;
+}
+
+/**
+ * Strip the conventional Java 'Event' suffix from an event class name
+ * before deriving the Kafka topic name.
+ * ProductPublishedEvent → ProductPublished → PRODUCT_PUBLISHED
+ *
+ * If the event has an explicit `topic:` property in domain.yaml, that takes
+ * precedence and this function is not called.
+ */
+function stripEventSuffix(name) {
+  return name.endsWith('Event') ? name.slice(0, -'Event'.length) : name;
+}
+
+/**
+ * Build a Kafka event generation context for a given domain event.
+ * Intended for use by `generate-entities.js` to auto-wire broker integration events
+ * without requiring a separate `eva g kafka-event` invocation.
+ *
+ * @param {string} packageName
+ * @param {string} moduleName
+ * @param {{ name: string, topic?: string, fields: Array }} domainEvent - Domain event from parsed domain.yaml
+ * @param {{ partitions?: number, replicas?: number }} [options]
+ * @returns {Object} context ready for generateSingleKafkaEvent()
+ */
+function buildKafkaEventContext(packageName, moduleName, domainEvent, { partitions = 3, replicas = 1 } = {}) {
+  const normalizedName = toPascalCase(domainEvent.name);
+  const integrationEventClassName = normalizedName.endsWith('IntegrationEvent')
+    ? normalizedName
+    : `${normalizedName}IntegrationEvent`;
+  // If an explicit topic is declared in domain.yaml, use it as source of truth.
+  // Otherwise strip the 'Event' suffix before deriving snake/kebab names so that
+  // ProductPublishedEvent → PRODUCT_PUBLISHED (not PRODUCT_PUBLISHED_EVENT).
+  const topicBase = domainEvent.topic
+    ? domainEvent.topic.trim().toUpperCase().replace(/-/g, '_')
+    : toSnakeCase(stripEventSuffix(domainEvent.name)).toUpperCase();
+  const topicNameSnake = topicBase;
+  const topicNameKebab = topicBase.toLowerCase().replace(/_/g, '-');
+  const topicNameCamel = toCamelCase(topicNameKebab);
+  const topicSpringProperty = `\${topics.${topicNameKebab}}`;
+  return {
+    packageName,
+    moduleName,
+    modulePascalCase: toPascalCase(moduleName),
+    moduleCamelCase: toCamelCase(moduleName),
+    kafkaMessageBrokerClassName: `${toPascalCase(moduleName)}KafkaMessageBroker`,
+    eventClassName: integrationEventClassName,
+    topicNameSnake,
+    topicNameKebab,
+    topicNameCamel,
+    topicPropertyKey: topicNameKebab,
+    topicPropertyValue: topicNameSnake,
+    topicSpringProperty,
+    partitions,
+    replicas,
+    eventFields: domainEvent.fields || null
+  };
+}
+
 module.exports = generateKafkaEventCommand;
+module.exports.generateSingleKafkaEvent = generateSingleKafkaEvent;
+module.exports.buildKafkaEventContext = buildKafkaEventContext;
+module.exports.getInstalledBroker = getInstalledBroker;
+module.exports.updateKafkaYml = updateKafkaYml;
+module.exports.generateEventRecord = generateEventRecord;
+module.exports.createOrUpdateMessageBroker = createOrUpdateMessageBroker;
+module.exports.updateDomainEventHandler = updateDomainEventHandler;

package/src/generators/base-generator.js

@@ -8,7 +8,7 @@ class BaseGenerator {
   constructor(context) {
     this.context = context;
     this.templatesDir = path.join(__dirname, '../../templates/base');
-    this.projectDir = path.join(process.cwd(), context.artifactId);
+    this.projectDir = path.join(process.cwd(), context.projectName);
   }
 
   async generate() {
@@ -63,6 +63,7 @@ class BaseGenerator {
     await fs.ensureDir(resources);
     await fs.ensureDir(path.join(resources, 'static'));
     await fs.ensureDir(path.join(resources, 'templates'));
+    await fs.ensureDir(path.join(this.projectDir, 'system'));
   }
 
   async generateApplication() {
@@ -130,6 +131,12 @@ class BaseGenerator {
       path.join(this.projectDir, 'README.md'));
     await this.generateFile('root/AGENTS.md.ejs', 
       path.join(this.projectDir, 'AGENTS.md'));
+    await this.generateFile('root/system.yaml.ejs', 
+      path.join(this.projectDir, 'system.yaml'));
+    await this.generateFile('root/skill-build-system-yaml.ejs', 
+      path.join(this.projectDir, '.agents', 'skills', 'build-system-yaml', 'SKILL.md'));
+    await this.generateFile('root/skill-build-domain-yaml-references-generate-entities.md.ejs', 
+      path.join(this.projectDir, '.agents', 'skills', 'build-system-yaml', 'references', 'GENERATE_ENTITIES.md'));
     
     if (this.context.features.includeDocker) {
       await this.generateFile('docker/docker-compose.yaml.ejs', 

package/src/generators/postman-generator.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const crypto = require('crypto');
+
+const { parseDomainYaml } = require('../utils/yaml-to-entity');
+const { renderTemplate } = require('../utils/template-engine');
+const { toKebabCase, toCamelCase, toPackagePath } = require('../utils/naming');
+const { initSeed, generateFakeValue, generateFakeBody, generateFakeId } = require('../utils/fake-data');
+
+const TEMPLATES_DIR = path.join(__dirname, '../../templates/postman');
+
+// Audit / internal fields excluded from command bodies
+const EXCLUDED_FIELDS = new Set([
+  'id', 'createdAt', 'updatedAt', 'createdBy', 'updatedBy', 'deletedAt',
+]);
+
+/**
+ * Determine which aggregate an operation belongs to based on use case naming.
+ * E.g. "CreateProduct" → "Product", "FindAllCategorys" → "Category".
+ *
+ * @param {string} useCase      - e.g. "CreateProduct"
+ * @param {Array}  aggregates   - parsed aggregates with `.name`
+ * @returns {string|null}       - aggregate name or null
+ */
+function resolveOwnerAggregate(useCase, aggregates) {
+  const ucLower = useCase.toLowerCase();
+  // Sort longest name first so "UserProfile" matches before "User"
+  const sorted = [...aggregates].sort((a, b) => b.name.length - a.name.length);
+  for (const agg of sorted) {
+    if (ucLower.includes(agg.name.toLowerCase())) return agg.name;
+  }
+  return null;
+}
+
+/**
+ * Generate a unified Postman collection covering every module in the system.
+ *
+ * @param {Object}   opts
+ * @param {string}   opts.projectDir     - Absolute path to the project root
+ * @param {string}   opts.systemDir      - Absolute path to the system/ directory
+ * @param {string}   opts.packageName    - Full Java package name (e.g. "com.example.myapp")
+ * @param {Object}   opts.systemConfig   - Parsed system.yaml object
+ * @param {Object}   opts.projectConfig  - Parsed .eva4j.json project config
+ * @returns {Promise<string|null>}       - Path to the generated file, or null on error
+ */
+async function generateUnifiedPostmanCollection({
+  projectDir,
+  systemDir,
+  packageName,
+  systemConfig,
+  projectConfig,
+}) {
+  const systemName = systemConfig.system?.name || projectConfig.projectName || projectConfig.artifactId || 'eva4j-app';
+  const port = projectConfig.server?.port || 8040;
+  const modules = systemConfig.modules || [];
+
+  if (!modules.length) return null;
+
+  // Seed faker for deterministic output
+  initSeed(42);
+
+  // ── Collect module contexts ───────────────────────────────────────────────
+  const moduleContexts = [];
+
+  for (const mod of modules) {
+    const yamlPath = path.join(systemDir, `${mod.name}.yaml`);
+    if (!(await fs.pathExists(yamlPath))) continue;
+
+    let parsed;
+    try {
+      parsed = await parseDomainYaml(yamlPath, packageName, mod.name);
+    } catch (err) {
+      console.log(chalk.yellow(`  ⚠️  Could not parse ${mod.name}.yaml for Postman: ${err.message}`));
+      continue;
+    }
+
+    const { aggregates, allEnums, endpoints } = parsed;
+    const aggregateContexts = [];
+
+    for (const agg of aggregates) {
+      const rootEntity = agg.rootEntity;
+      const idField = rootEntity.fields.find(f => f.name === 'id');
+      const idType = idField ? idField.javaType : 'String';
+      const exampleId = generateFakeId(idType);
+      const trackUser = rootEntity.audit?.trackUser === true;
+      const valueObjects = agg.valueObjects || [];
+
+      // Command fields: exclude id, audit, readOnly, deletedAt
+      const commandFields = rootEntity.fields.filter(
+        f => !EXCLUDED_FIELDS.has(f.name) && !f.readOnly
+      );
+
+      // Build fake body for create/update
+      const defaultBody = generateFakeBody(commandFields, [], allEnums, valueObjects);
+
+      if (endpoints && endpoints.versions && endpoints.versions.length > 0) {
+        // ── Endpoint-driven ───────────────────────────────────────────────
+        const operations = [];
+        const bodies = {};
+
+        for (const version of endpoints.versions) {
+          for (const op of version.operations) {
+            // Classify operation → which aggregate it belongs to
+            const owner = resolveOwnerAggregate(op.useCase, aggregates);
+            if (owner && owner !== agg.name) continue;
+            // If no aggregate could be resolved, assign to the first aggregate
+            if (!owner && agg !== aggregates[0]) continue;
+
+            const basePath = endpoints.basePath || '/';
+            operations.push({
+              useCase: op.useCase,
+              method: op.method,
+              path: op.path || '/',
+              basePath,
+              version: version.version,
+            });
+
+            // Generate body for write operations
+            if (op.method === 'POST' || op.method === 'PUT' || op.method === 'PATCH') {
+              // Re-seed per operation so bodies vary
+              bodies[op.useCase] = generateFakeBody(commandFields, [], allEnums, valueObjects);
+            }
+          }
+        }
+
+        aggregateContexts.push({
+          name: agg.name,
+          trackUser,
+          idType,
+          exampleId,
+          resourceNameKebab: toKebabCase(agg.name),
+          operations,
+          defaultCrud: false,
+          bodies,
+        });
+      } else {
+        // ── Default CRUD (no endpoints section) ──────────────────────────
+        aggregateContexts.push({
+          name: agg.name,
+          trackUser,
+          idType,
+          exampleId,
+          resourceNameKebab: toKebabCase(agg.name),
+          operations: null,
+          defaultCrud: true,
+          bodies: { default: defaultBody },
+        });
+      }
+    }
+
+    if (aggregateContexts.length > 0) {
+      moduleContexts.push({
+        name: mod.name,
+        aggregates: aggregateContexts,
+      });
+    }
+  }
+
+  if (!moduleContexts.length) return null;
+
+  // ── Render template ─────────────────────────────────────────────────────
+  const templatePath = path.join(TEMPLATES_DIR, 'UnifiedCollection.json.ejs');
+  const collectionId = crypto.randomUUID();
+
+  const context = {
+    systemName,
+    collectionId,
+    port,
+    modules: moduleContexts,
+  };
+
+  const content = await renderTemplate(templatePath, context);
+
+  // ── Write output ────────────────────────────────────────────────────────
+  const outputDir = path.join(projectDir, 'postman');
+  await fs.ensureDir(outputDir);
+
+  const outputFileName = `${toKebabCase(systemName)}-Postman-Collection.json`;
+  const outputPath = path.join(outputDir, outputFileName);
+  await fs.writeFile(outputPath, content, 'utf-8');
+
+  return outputPath;
+}
+
+module.exports = { generateUnifiedPostmanCollection };

package/src/generators/shared-generator.js

@@ -194,6 +194,12 @@ class SharedGenerator {
       path.join(handlerExceptionPath, 'HandlerExceptions.java'));
   }
 
+  async generateMockEvent(basePath) {
+    const destPath = path.join(basePath, 'infrastructure', 'mockEvent', 'MockEvent.java');
+    const templatePath = path.join(__dirname, '../../templates/mock/MockEvent.java.ejs');
+    await renderAndWrite(templatePath, destPath, this.context, { overwrite: false });
+  }
+
   async generateConfigurations(basePath) {
     const configurationsPath = path.join(basePath, 'infrastructure', 'configurations');
     
@@ -209,6 +215,10 @@ class SharedGenerator {
     await this.generateFile('configurations/swaggerConfig/SwaggerConfig.java.ejs', 
       path.join(configurationsPath, 'swaggerConfig', 'SwaggerConfig.java'));
     
+    // Event publication schema fix (Spring Modulith varchar(255) → TEXT)
+    await this.generateFile('configurations/eventPublicationConfig/EventPublicationSchemaConfig.java.ejs', 
+      path.join(configurationsPath, 'eventPublicationConfig', 'EventPublicationSchemaConfig.java'));
+
     // UseCase config
     await this.generateFile('configurations/useCaseConfig/UseCaseAutoRegister.java.ejs', 
       path.join(configurationsPath, 'useCaseConfig', 'UseCaseAutoRegister.java'));

package/src/utils/config-manager.js

@@ -151,6 +151,60 @@ class ConfigManager {
 
     return config;
   }
+
+  /**
+   * Persist mock backup data into .eva4j.json so it survives process restarts.
+   * @param {Object} backups - Map of { key: { path, content } }
+   */
+  async saveMockBackup(backups, opts = {}) {
+    const config = await this.loadProjectConfig();
+    if (!config) throw new Error('Project configuration not found.');
+
+    config._mockBackup = {};
+    for (const [key, { path: filePath, content }] of Object.entries(backups)) {
+      config._mockBackup[key] = { path: filePath, content };
+    }
+    config._mockActive = true;
+    if (opts.onlyBroker) {
+      config._mockOnlyBroker = true;
+    }
+    config.updatedAt = new Date().toISOString();
+    await fs.writeJson(this.configFile, config, { spaces: 2 });
+  }
+
+  /**
+   * Read and clear mock backup from .eva4j.json.
+   * @returns {Object|null} backups map or null if no mock backup stored
+   */
+  async popMockBackup() {
+    const config = await this.loadProjectConfig();
+    if (!config || !config._mockBackup) return null;
+
+    const backups = config._mockBackup;
+    delete config._mockBackup;
+    delete config._mockActive;
+    delete config._mockOnlyBroker;
+    config.updatedAt = new Date().toISOString();
+    await fs.writeJson(this.configFile, config, { spaces: 2 });
+    return backups;
+  }
+
+  /**
+   * Returns true if a mock backup is currently stored in .eva4j.json.
+   */
+  async hasMockBackup() {
+    const config = await this.loadProjectConfig();
+    return !!(config && config._mockActive);
+  }
+
+  /**
+   * Returns true if the active mock was started with --only-broker
+   * (i.e. only the broker was swapped, DB config was kept unchanged).
+   */
+  async hasMockOnlyBroker() {
+    const config = await this.loadProjectConfig();
+    return !!(config && config._mockOnlyBroker);
+  }
 }
 
 module.exports = ConfigManager;

package/src/utils/context-builder.js

@@ -30,6 +30,7 @@ function buildBaseContext(answers) {
     dependencyManagementVersion: defaults.dependencyManagementVersion,
     springModulithVersion: defaults.springModulithVersion,
     springCloudVersion: defaults.springCloudVersion,
+    springdocVersion: defaults.springdocVersion,
     gradleVersion: defaults.gradleVersion,
     dependencies: answers.dependencies || [],
     author: answers.author || 'Generated by eva4j',

package/src/utils/domain-diagram.js

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * Generates Mermaid classDiagram text per module from parsed domain.yaml objects.
+ *
+ * @param {Object} domainConfigs  Plain object { [moduleName]: parsedDomainYaml }
+ * @returns {{ [moduleName]: string }}  Map of module → Mermaid diagram text (empty string if no aggregates)
+ */
+function generateDomainDiagrams(domainConfigs) {
+  const result = {};
+  for (const [moduleName, config] of Object.entries(domainConfigs)) {
+    result[moduleName] = generateModuleDiagram(moduleName, config);
+  }
+  return result;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const AUDIT_FIELDS = new Set(['createdAt', 'updatedAt', 'createdBy', 'updatedBy']);
+
+/** Normalize to PascalCase (capitalize first letter only). */
+function toPascal(name) {
+  if (!name) return name;
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+function fieldPrefix(field) {
+  if (field.hidden) return '-';
+  if (field.readOnly) return '~';
+  return '+';
+}
+
+// ── Per-module diagram builder ────────────────────────────────────────────────
+
+function generateModuleDiagram(moduleName, config) {
+  const aggregates = config.aggregates || [];
+  if (aggregates.length === 0) return '';
+
+  // Flat diagram — namespace blocks are avoided because Mermaid's layout engine
+  // can place inner classes outside the visual boundary, causing overflow.
+  // Aggregates are separated by %% comment dividers instead.
+  const lines = ['classDiagram'];
+  const relationships = []; // Collected per-aggregate, emitted at the end
+  const notes = [];         // `note for ClassName "..."` — for cross-aggregate refs
+
+  // Build a set of all entity/VO/enum PascalCase class names defined in this module
+  // so we can distinguish intra-module from cross-aggregate relationships.
+  const localClasses = new Set();
+  for (const aggregate of aggregates) {
+    for (const e of aggregate.entities || []) localClasses.add(toPascal(e.name));
+    for (const v of aggregate.valueObjects || []) localClasses.add(toPascal(v.name));
+    for (const en of aggregate.enums || []) localClasses.add(toPascal(en.name));
+  }
+
+  for (const aggregate of aggregates) {
+    const entities = aggregate.entities || [];
+    const valueObjects = aggregate.valueObjects || [];
+    const enums = aggregate.enums || [];
+
+    lines.push('');
+    lines.push(`  %% ── Aggregate: ${aggregate.name} ─────────────────────`);
+
+    // ── Entities ─────────────────────────────────────────────────────────────
+    for (const entity of entities) {
+      const className = toPascal(entity.name);
+      lines.push(`  class ${className} {`);
+      lines.push(`    ${entity.isRoot ? '<<aggregate root>>' : '<<entity>>'}`);
+
+      for (const field of entity.fields || []) {
+        if (AUDIT_FIELDS.has(field.name)) continue;
+        lines.push(`    ${fieldPrefix(field)}${field.type} ${field.name}`);
+      }
+
+      if (entity.audit?.enabled) {
+        lines.push(`    +LocalDateTime createdAt`);
+        lines.push(`    +LocalDateTime updatedAt`);
+      }
+      if (entity.audit?.trackUser) {
+        lines.push(`    +String createdBy`);
+        lines.push(`    +String updatedBy`);
+      }
+
+      lines.push(`  }`);
+    }
+
+    // ── Value objects ─────────────────────────────────────────────────────────
+    for (const vo of valueObjects) {
+      const className = toPascal(vo.name);
+      lines.push(`  class ${className} {`);
+      lines.push(`    <<value object>>`);
+      for (const field of vo.fields || []) {
+        lines.push(`    +${field.type} ${field.name}`);
+      }
+      lines.push(`  }`);
+    }
+
+    // ── Enums ─────────────────────────────────────────────────────────────────
+    for (const en of enums) {
+      const className = toPascal(en.name);
+      lines.push(`  class ${className} {`);
+      lines.push(`    <<enumeration>>`);
+      for (const val of en.values || []) {
+        lines.push(`    ${val}`);
+      }
+      lines.push(`  }`);
+    }
+
+    // ── Collect relationships ─────────────────────────────────────────────────
+    const voNames = new Set(valueObjects.map((v) => toPascal(v.name)));
+    const enumNames = new Set(enums.map((e) => toPascal(e.name)));
+
+    for (const entity of entities) {
+      const srcClass = toPascal(entity.name);
+
+      // Structural JPA relationships — only emit if target is a local class
+      for (const rel of entity.relationships || []) {
+        const target = toPascal(rel.target || rel.targetEntity || '');
+        if (!target) continue;
+        if (!localClasses.has(target)) continue; // skip cross-aggregate targets
+        const label = rel.mappedBy ? ` : ${rel.mappedBy}` : '';
+        switch (rel.type) {
+          case 'OneToMany':
+            relationships.push(`  ${srcClass} "1" --o "*" ${target}${label}`);
+            break;
+          case 'OneToOne':
+            relationships.push(`  ${srcClass} "1" --o "1" ${target}${label}`);
+            break;
+          case 'ManyToOne':
+            relationships.push(`  ${srcClass} "*" --> "1" ${target}`);
+            break;
+          case 'ManyToMany':
+            relationships.push(`  ${srcClass} "*" --> "*" ${target}`);
+            break;
+          default:
+            relationships.push(`  ${srcClass} --> ${target}${label}`);
+        }
+      }
+
+      // Field-level type references within the same module (deduplicated)
+      const seenEdges = new Set();
+      const crossRefs = []; // cross-aggregate reference fields for this entity
+
+      for (const field of entity.fields || []) {
+        if (AUDIT_FIELDS.has(field.name)) continue;
+
+        const fieldType = toPascal(field.type);
+
+        if (enumNames.has(fieldType)) {
+          const key = `${srcClass}-->${fieldType}`;
+          if (!seenEdges.has(key)) {
+            relationships.push(`  ${srcClass} --> ${fieldType} : ${field.name}`);
+            seenEdges.add(key);
+          }
+        } else if (voNames.has(fieldType)) {
+          const key = `${srcClass}*--${fieldType}`;
+          if (!seenEdges.has(key)) {
+            relationships.push(`  ${srcClass} *-- ${fieldType} : ${field.name}`);
+            seenEdges.add(key);
+          }
+        } else if (field.reference) {
+          // Cross-aggregate reference: render as a note instead of an arrow
+          // to avoid undefined ghost nodes appearing outside the diagram.
+          const refModule = field.reference.module;
+          const refAggregate = field.reference.aggregate;
+          const label =
+            refModule && refModule !== moduleName
+              ? `${field.name} → ${refAggregate} (${refModule})`
+              : `${field.name} → ${refAggregate}`;
+          crossRefs.push(label);
+        }
+      }
+
+      if (crossRefs.length > 0) {
+        notes.push(`  note for ${srcClass} "refs: ${crossRefs.join(', ')}"`);
+      }
+    }
+  }
+
+  if (relationships.length > 0) {
+    lines.push('');
+    lines.push(...relationships);
+  }
+
+  if (notes.length > 0) {
+    lines.push('');
+    lines.push(...notes);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { generateDomainDiagrams };