feat(api)!: update entity output for having relations grouped

docs/src/concepts/entities.md

@@ -54,8 +54,7 @@ Here's an entity instantiated from the `web-service` template:
         "name": "Web API 1"
       }
     ]
-  },
-  "relations_as_target": {}
+  }
 }
 ```
 
@@ -220,6 +219,25 @@ When creating an entity, you specify relations as an array of objects, each with
 }
 ```
 
+### One-to-Many Relations (`to_many: true`)
+
+When multiple related entities are allowed, list several identifiers:
+
+```json
+{
+  "relations": [
+    {
+      "name": "components",
+      "target_entity_identifiers": [
+        "frontend",
+        "backend",
+        "database"
+      ]
+    }
+  ]
+}
+```
+
 ### Relations in Responses
 
 In API responses, relations are grouped by name and include summary information about each target entity:
@@ -237,56 +255,10 @@ In API responses, relations are grouped by name and include summary information
         "name": "Web API 2"
       }
     ]
-  },
-  "relations_as_target": {
-    "depends-on": [
-      {
-        "identifier": "frontend-app",
-        "name": "Frontend App"
-      }
-    ]
   }
 }
 ```
 
-The `relations_as_target` field shows reverse relationships—other entities that reference this entity.
-
-### One-to-One Relations (`to_many: false`)
-
-For consistency, even single relations are represented as arrays:
-
-```json
-{
-  "relations": [
-    {
-      "name": "owned_by",
-      "target_entity_identifiers": [
-        "platform-team"
-      ]
-    }
-  ]
-}
-```
-
-### One-to-Many Relations (`to_many: true`)
-
-When multiple related entities are allowed, list several identifiers:
-
-```json
-{
-  "relations": [
-    {
-      "name": "components",
-      "target_entity_identifiers": [
-        "frontend",
-        "backend",
-        "database"
-      ]
-    }
-  ]
-}
-```
-
 ---
 
 ## Retrieving Entities
@@ -386,8 +358,7 @@ curl -X PUT http://localhost:8084/api/v1/entities/web-service/my-web-service \
     "protocol": "HTTP",
     "programmingLanguage": "JAVA"
   },
-  "relations": {},
-  "relations_as_target": {}
+  "relations": {}
 }
 ```
 

docs/src/concepts/entity-filtering.md

@@ -103,7 +103,7 @@ relation.database.name:prod
 
 #### Reverse Relation Filters
 
-Use `relations_as_target.<name>.<property>` to find entities that _appear as targets_ in a relation of type `<name>`. The `<property>` must be `identifier` or `name` and refers to the **source** entity in that relation.
+Use `relations_as_target.<name>.<property>` to find entities that have inbound relation of type `<name>`. The `<property>` must be `identifier` or `name` and refers to the **source** entity in that relation.
 
 ```text
 relations_as_target.owned_by.name:platform-team

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

@@ -11,6 +11,7 @@
 /// - Dependency impact analysis before entity deletion
 /// - Bidirectional relationship navigation
 /// - Audit trails for relationship changes
+/// - Template-aware relation summaries for unified API responses
 public record RelationAsTargetSummary(String targetEntityIdentifier, String relationName,
-    String sourceEntityIdentifier, String sourceEntityName) {
+    String sourceEntityIdentifier, String sourceEntityName, String sourceTemplateIdentifier) {
 }

src/main/java/com/decathlon/idp_core/domain/model/entity_graph/FlowDirection.java

@@ -0,0 +1,15 @@
+package com.decathlon.idp_core.domain.model.entity_graph;
+
+/// Internal flow direction states used during graph traversal.
+///
+/// Maps to relationship directions (outbound vs inbound) during BFS propagation.
+/// This enum is used internally by [EntityGraphHelper] to track traversal flow
+/// and should not be exposed in public APIs.
+public enum FlowDirection {
+  /// Follow outbound relationships only (downstream dependencies)
+  OUTBOUND,
+  /// Follow inbound relationships only (upstream dependents)
+  INBOUND,
+  /// Follow both outbound and inbound relationships
+  ANY
+}

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

@@ -1,5 +1,6 @@
 package com.decathlon.idp_core.domain.port;
 
+import java.util.Collection;
 import java.util.Map;
 import java.util.UUID;
 
@@ -50,7 +51,7 @@ public interface EntityGraphRepositoryPort {
   /// @return an immutable map of all discovered entities keyed by their UUID,
   /// including the root entity. Returns an empty map if the root entity
   /// does not exist.
-  Map<UUID, Entity> findEntityGraph(UUID entityId, int depth, boolean includeProperties,
+  Map<UUID, Entity> findEntityGraph(Collection<UUID> rootIds, int depth, boolean includeProperties,
       EntityGraphTraversalMode mode);
 
 }