perf(core): cut ORM/REST serialization overhead for entity template and graph endpoints

pom.xml

@@ -130,6 +130,18 @@
       <artifactId>spring-boot-starter-data-jpa</artifactId>
     </dependency>
 
+    <!-- Caching abstraction (Caffeine backend) for read-mostly domain lookups
+         such as EntityTemplate resolution, avoiding a DB round trip on every
+         entity read/write path (perf #131) -->
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-cache</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.github.ben-manes.caffeine</groupId>
+      <artifactId>caffeine</artifactId>
+    </dependency>
+
     <!-- Spring Boot DevTools for hot reloading -->
     <dependency>
       <groupId>org.springframework.boot</groupId>

src/main/java/com/decathlon/idp_core/domain/model/entity/EntityIdentity.java

@@ -0,0 +1,18 @@
+package com.decathlon.idp_core.domain.model.entity;
+
+import java.util.UUID;
+
+/// Lightweight projection carrying only the identifying fields of an
+/// [Entity] — `id`, `templateIdentifier`, `identifier`, `name` — without its
+/// properties or relations.
+///
+/// **Business purpose:** Some callers only need to resolve which entity a
+/// business key (`templateIdentifier` + `identifier`) refers to, including
+/// its technical UUID, without paying the cost of hydrating and mapping the
+/// full property/relation graph. The primary consumer is graph traversal
+/// (`EntityGraphService#getEntityGraph`), which resolves the root entity's
+/// identity here and then loads its relationship graph via a dedicated batch
+/// query — the properties/relations on the root [Entity] would otherwise be
+/// discarded, so fetching them was pure overhead (perf #131).
+public record EntityIdentity(UUID id, String templateIdentifier, String identifier, String name) {
+}

src/main/java/com/decathlon/idp_core/domain/port/EntityRepositoryPort.java

@@ -11,6 +11,7 @@
 import com.decathlon.idp_core.domain.model.entity.Entity;
 import com.decathlon.idp_core.domain.model.entity.EntityCompositeKey;
 import com.decathlon.idp_core.domain.model.entity.EntityFilter;
+import com.decathlon.idp_core.domain.model.entity.EntityIdentity;
 import com.decathlon.idp_core.domain.model.entity.EntitySummary;
 import com.decathlon.idp_core.domain.model.search.PaginatedResult;
 import com.decathlon.idp_core.domain.model.search.PaginationCriteria;
@@ -41,6 +42,21 @@ public interface EntityRepositoryPort {
   Optional<Entity> findByTemplateIdentifierAndIdentifier(String templateIdentifier,
       String identifier);
 
+  /// Resolves only the identifying fields (id, templateIdentifier, identifier,
+  /// name) of an entity, without hydrating its properties or relations.
+  ///
+  /// **Performance:** Use this instead of
+  /// [#findByTemplateIdentifierAndIdentifier] when the caller only needs to
+  /// resolve the entity's identity — e.g. before dispatching a separate batch
+  /// graph query — to avoid the cost of lazily loading and mapping the full
+  /// property/relation collections (perf #131).
+  ///
+  /// @param templateIdentifier business template identifier
+  /// @param identifier business identifier within the template
+  /// @return the matching entity's identity, or empty if none found
+  Optional<EntityIdentity> findIdentityByTemplateIdentifierAndIdentifier(String templateIdentifier,
+      String identifier);
+
   Optional<Entity> findByTemplateIdentifierAndName(String templateIdentifier, String entityName);
 
   Page<Entity> findByTemplateIdentifier(String templateIdentifier, Pageable pageable);

src/main/java/com/decathlon/idp_core/domain/service/entity_graph/EntityGraphService.java

@@ -15,6 +15,7 @@
 import com.decathlon.idp_core.domain.exception.entity_template.EntityTemplateNotFoundException;
 import com.decathlon.idp_core.domain.model.entity.Entity;
 import com.decathlon.idp_core.domain.model.entity.EntityFilter;
+import com.decathlon.idp_core.domain.model.entity.EntityIdentity;
 import com.decathlon.idp_core.domain.model.entity_graph.EntityGraphNode;
 import com.decathlon.idp_core.domain.model.entity_graph.EntityGraphTraversalMode;
 import com.decathlon.idp_core.domain.port.EntityGraphRepositoryPort;
@@ -104,9 +105,12 @@ public EntityGraphNode getEntityGraph(String templateIdentifier, String entityId
 
     entityTemplateValidationService.validateTemplateExists(templateIdentifier);
 
-    // 1. Resolve root entity
-    Entity rootEntity = entityRepositoryPort
-        .findByTemplateIdentifierAndIdentifier(templateIdentifier, entityIdentifier)
+    // 1. Resolve root entity identity only — properties/relations are not
+    // needed here since the graph data comes from the batch findEntityGraph
+    // call below; fetching the full Entity would force Hibernate to
+    // lazy-load both collections for no benefit (perf #131).
+    EntityIdentity rootEntity = entityRepositoryPort
+        .findIdentityByTemplateIdentifierAndIdentifier(templateIdentifier, entityIdentifier)
         .orElseThrow(() -> new EntityNotFoundException(templateIdentifier, entityIdentifier));
 
     // 2. Load the graph footprint via optimized DB calls

src/main/java/com/decathlon/idp_core/domain/service/entity_template/EntityTemplateService.java

@@ -11,6 +11,9 @@
 import jakarta.transaction.Transactional;
 import jakarta.validation.Valid;
 
+import org.springframework.cache.annotation.CacheEvict;
+import org.springframework.cache.annotation.Cacheable;
+import org.springframework.cache.annotation.Caching;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
 import org.springframework.stereotype.Service;
@@ -45,6 +48,19 @@
 @RequiredArgsConstructor
 public class EntityTemplateService {
 
+  /// Name of the cache backing {@link #getEntityTemplateByIdentifier(String)}.
+  ///
+  /// **Business purpose:** `EntityTemplate` lookups happen on nearly every
+  /// entity read/write request (property type resolution, relation target
+  /// template resolution — see `EntityDtoOutMapper`, `EntityService`,
+  /// `EntityGraphService`) but template definitions change infrequently
+  /// (admin-driven CRUD). Caching removes a redundant DB round trip from
+  /// every entity operation (perf #131). The cache backend (Caffeine, TTL,
+  /// size bound) is configured in the Infrastructure layer
+  /// (`CacheConfiguration`); this constant is the single source of truth for
+  /// the cache name so eviction and population always target the same cache.
+  public static final String ENTITY_TEMPLATES_CACHE = "entityTemplates";
+
   private final EntityTemplateRepositoryPort entityTemplateRepositoryPort;
   private final EntityTemplateValidationService entityTemplateValidationService;
   private final EntityRepositoryPort entityRepositoryPort;
@@ -70,9 +86,18 @@
   /// Case-sensitive matching ensures precise template resolution for entity
   /// operations.
   ///
+  /// **Performance:** Cached by identifier (see [#ENTITY_TEMPLATES_CACHE]) —
+  /// this method is called on nearly every entity read/write path, and
+  /// template definitions rarely change, so caching removes a redundant DB
+  /// round trip per call (perf #131). Mutating operations
+  /// ([#createEntityTemplate], [#updateEntityTemplate],
+  /// [#deleteEntityTemplate]) evict the corresponding entry to keep the cache
+  /// consistent with persisted state.
+  ///
   /// @param identifier unique business identifier of the template
   /// @return the matching [EntityTemplate]
   /// @throws EntityTemplateNotFoundException when template doesn't exist
+  @Cacheable(cacheNames = ENTITY_TEMPLATES_CACHE, key = "#identifier")
   public EntityTemplate getEntityTemplateByIdentifier(String identifier) {
     return entityTemplateRepositoryPort.findByIdentifier(identifier)
         .orElseThrow(() -> new EntityTemplateNotFoundException("identifier", identifier));
@@ -98,6 +123,7 @@
   /// @throws EntityTemplateAlreadyExistsException when identifier already exists
   /// @throws EntityTemplateNameAlreadyExistsException when name already exists
   @Transactional
+  @CacheEvict(cacheNames = ENTITY_TEMPLATES_CACHE, key = "#entityTemplate.identifier()")
   public EntityTemplate createEntityTemplate(@Valid EntityTemplate entityTemplate) {
     entityTemplateValidationService.validateForCreation(entityTemplate);
     return entityTemplateRepositoryPort.save(entityTemplate);
@@ -137,9 +163,11 @@
   /// @throws EntityTemplateAlreadyExistsException when renaming would cause a
   /// duplicate
   @Transactional
+  @Caching(evict = {@CacheEvict(cacheNames = ENTITY_TEMPLATES_CACHE, key = "#identifier"),
+      @CacheEvict(cacheNames = ENTITY_TEMPLATES_CACHE, key = "#entityTemplate.identifier()")})
   public EntityTemplate updateEntityTemplate(String identifier,
       @Valid EntityTemplate entityTemplate) {
     EntityTemplate existingTemplate = getEntityTemplateByIdentifier(identifier);
     EntityTemplate mergedTemplate = new EntityTemplate(existingTemplate.id(),
         entityTemplate.identifier(), entityTemplate.name(), entityTemplate.description(),
         mergePropertyDefinitions(existingTemplate.propertiesDefinitions(),
@@ -167,6 +195,7 @@
   /// @param identifier unique business identifier of template to delete
   /// @throws EntityTemplateNotFoundException when template doesn't exist
   @Transactional
+  @CacheEvict(cacheNames = ENTITY_TEMPLATES_CACHE, key = "#identifier")
   public void deleteEntityTemplate(String identifier) {
     entityTemplateValidationService.validateForDeletion(identifier);
     entityTemplateRepositoryPort.deleteByIdentifier(identifier);

src/main/java/com/decathlon/idp_core/infrastructure/adapters/persistence/PostgresEntityAdapter.java

@@ -18,6 +18,7 @@
 import com.decathlon.idp_core.domain.model.entity.Entity;
 import com.decathlon.idp_core.domain.model.entity.EntityCompositeKey;
 import com.decathlon.idp_core.domain.model.entity.EntityFilter;
+import com.decathlon.idp_core.domain.model.entity.EntityIdentity;
 import com.decathlon.idp_core.domain.model.entity.EntitySummary;
 import com.decathlon.idp_core.domain.model.search.PaginatedResult;
 import com.decathlon.idp_core.domain.model.search.PaginationCriteria;
@@ -65,6 +66,13 @@ public Optional<Entity> findByTemplateIdentifierAndIdentifier(String templateIde
         .map(mapper::toDomain);
   }
 
+  @Override
+  public Optional<EntityIdentity> findIdentityByTemplateIdentifierAndIdentifier(
+      String templateIdentifier, String identifier) {
+    return jpaEntityRepository.findIdentityByTemplateIdentifierAndIdentifier(templateIdentifier,
+        identifier);
+  }
+
   @Override
   public Optional<Entity> findByTemplateIdentifierAndName(String templateIdentifier,
       String entityName) {

src/main/java/com/decathlon/idp_core/infrastructure/adapters/persistence/configuration/CacheConfiguration.java

@@ -0,0 +1,40 @@
+package com.decathlon.idp_core.infrastructure.adapters.persistence.configuration;
+
+import java.util.concurrent.TimeUnit;
+
+import org.springframework.cache.CacheManager;
+import org.springframework.cache.annotation.EnableCaching;
+import org.springframework.cache.caffeine.CaffeineCacheManager;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import com.decathlon.idp_core.domain.service.entity_template.EntityTemplateService;
+import com.github.benmanes.caffeine.cache.Caffeine;
+
+/// Cache configuration backing read-mostly domain lookups that would
+/// otherwise hit the database on every call.
+///
+/// **Business purpose:** `EntityTemplate` definitions are read on nearly every
+/// entity read/write request (property type resolution, relation target
+/// template resolution) but change infrequently (admin-driven CRUD). Caching
+/// them removes a redundant DB round trip from every entity operation without
+/// affecting correctness, since template mutations explicitly evict their
+/// cache entry (see [EntityTemplateService]).
+///
+/// **Why Caffeine:** high-performance, near-optimal caching library with a
+/// simple size/time-bound eviction policy — avoids unbounded memory growth
+/// while keeping hot templates resident.
+@Configuration
+@EnableCaching
+public class CacheConfiguration {
+
+  @Bean
+  public CacheManager cacheManager() {
+    CaffeineCacheManager cacheManager = new CaffeineCacheManager(
+        EntityTemplateService.ENTITY_TEMPLATES_CACHE);
+    cacheManager.setCaffeine(Caffeine.newBuilder().maximumSize(500)
+        .expireAfterWrite(10, TimeUnit.MINUTES).recordStats());
+    return cacheManager;
+  }
+
+}

src/main/java/com/decathlon/idp_core/infrastructure/adapters/persistence/repository/JpaEntityRepository.java

@@ -14,6 +14,7 @@
 import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;
 
+import com.decathlon.idp_core.domain.model.entity.EntityIdentity;
 import com.decathlon.idp_core.domain.model.entity.EntitySummary;
 import com.decathlon.idp_core.infrastructure.adapters.persistence.model.entity.EntityJpaEntity;
 
@@ -66,6 +67,21 @@ List<EntitySummary> findByCompositeKeys(
   Optional<EntityJpaEntity> findByTemplateIdentifierAndIdentifier(String templateIdentifier,
       String identifier);
 
+  /// Resolves only the identifying scalar fields of an entity (id,
+  /// templateIdentifier, identifier, name) via a constructor expression,
+  /// without touching the lazy `properties`/`relations` collections.
+  ///
+  /// **Performance:** Avoids the extra batched lazy-load queries that
+  /// `findByTemplateIdentifierAndIdentifier` triggers as soon as the mapper
+  /// touches `getProperties()`/`getRelations()` on the returned entity —
+  /// useful for callers that only need to resolve identity before a separate
+  /// batch graph query (perf #131).
+  @Query("SELECT new com.decathlon.idp_core.domain.model.entity.EntityIdentity(e.id, e.templateIdentifier, e.identifier, e.name) "
+      + "FROM EntityJpaEntity e WHERE e.templateIdentifier = :templateIdentifier AND e.identifier = :identifier")
+  Optional<EntityIdentity> findIdentityByTemplateIdentifierAndIdentifier(
+      @Param("templateIdentifier") String templateIdentifier,
+      @Param("identifier") String identifier);
+
   Optional<EntityJpaEntity> findByTemplateIdentifierAndName(String templateIdentifier, String name);
 
   Page<EntityJpaEntity> findByTemplateIdentifier(String templateIdentifier, Pageable pageable);