feat: replicate element relationships onto instances

Author: yt-ms

src/structurizr/model/deployment_node.py

@@ -175,11 +175,16 @@ def add_container(
             + 1
         )
         instance = ContainerInstance(
-            container=container, instance_id=instance_id, parent=self
+            container=container,
+            instance_id=instance_id,
+            environment=self.environment,
+            parent=self,
         )
         self._container_instances.add(instance)
         model = self.model
         model += instance
+        if replicate_relationships:
+            instance.replicate_element_relationships()
         return instance
 
     def add_software_system(
@@ -206,11 +211,16 @@ def add_software_system(
             + 1
         )
         instance = SoftwareSystemInstance(
-            software_system=software_system, instance_id=instance_id, parent=self
+            software_system=software_system,
+            instance_id=instance_id,
+            environment=self.environment,
+            parent=self,
         )
         self._software_system_instances.add(instance)
         model = self.model
         model += instance
+        if replicate_relationships:
+            instance.replicate_element_relationships()
         return instance
 
     def add_infrastructure_node(self, name: str, **kwargs) -> InfrastructureNode:

src/structurizr/model/static_structure_element_instance.py

@@ -17,7 +17,7 @@
 
 
 from abc import ABC
-from typing import Iterable, List, Optional
+from typing import TYPE_CHECKING, Iterable, List, Optional, Set
 
 from pydantic import Field
 
@@ -26,6 +26,9 @@
 from .static_structure_element import StaticStructureElement
 
 
+if TYPE_CHECKING:
+    from .deployment_node import DeploymentNode
+
 __all__ = ("StaticStructureElementInstance", "StaticStructureElementInstanceIO")
 
 
@@ -60,6 +63,44 @@ def __init__(
         self.health_checks = set(health_checks)
         self.parent = parent
 
+    def replicate_element_relationships(self):
+        """
+        Replicate relationships from the element of this instance.
+
+        This looks at the relationships to and from the element of this instance and
+        sets up the equivalent relationships between the corresponding instances in
+        the same environment.
+        """
+        # Find all the element instances in the same deployment environment
+        element_instances: Set[StaticStructureElementInstance] = {
+            e
+            for e in self.model.get_elements()
+            if isinstance(e, StaticStructureElementInstance)
+            and e.environment == self.environment
+        }
+
+        for other_element_instance in element_instances:
+            other_element = other_element_instance.element
+
+            for relationship in self.element.relationships:
+                if relationship.destination is other_element:
+                    self.add_relationship(
+                        destination=other_element_instance,
+                        description=relationship.description,
+                        technology=relationship.technology,
+                        interaction_style=relationship.interaction_style,
+                        linked_relationship_id=relationship.id,
+                    ).tags.clear()
+            for relationship in other_element.relationships:
+                if relationship.destination is self.element:
+                    other_element_instance.add_relationship(
+                        destination=self,
+                        description=relationship.description,
+                        technology=relationship.technology,
+                        interaction_style=relationship.interaction_style,
+                        linked_relationship_id=relationship.id,
+                    ).tags.clear()
+
     @classmethod
     def hydrate_arguments(cls, instance_io: StaticStructureElementInstanceIO) -> dict:
         """Build constructor arguments from IO."""

tests/integration/test_relationship_replication.py

@@ -0,0 +1,147 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Test the behaviour when replicating relationships to element instances."""
+
+
+import pytest
+
+from structurizr.model import InteractionStyle, Model
+
+
+@pytest.fixture(scope="function")
+def empty_model() -> Model:
+    """Provide an new empty model on demand for test cases to use."""
+    return Model()
+
+
+def test_replication_adds_relationships_in_the_same_environment(empty_model: Model):
+    """Ensure within the same environment, relationships are replicated."""
+    # Adapted from the Java ModelTests
+    model = empty_model
+    system1 = model.add_software_system("Software System 1")
+    container1 = system1.add_container("Container 1")
+
+    system2 = model.add_software_system("Software System 2")
+    container2 = system2.add_container("Container 2")
+
+    system3 = model.add_software_system("Software System 3")
+    container3 = system3.add_container("Container 3")
+
+    system4 = model.add_software_system("Software System 4")
+
+    container1.uses(
+        container2,
+        "Uses 1",
+        "Technology 1",
+        interaction_style=InteractionStyle.Synchronous,
+    )
+    container2.uses(
+        container3,
+        "Uses 2",
+        "Technology 2",
+        interaction_style=InteractionStyle.Asynchronous,
+    )
+    container3.uses(system4)
+
+    dev_deployment_node = model.add_deployment_node(
+        "Deployment Node", environment="Development"
+    )
+    container_instance1 = dev_deployment_node.add_container(container1)
+    container_instance2 = dev_deployment_node.add_container(container2)
+    container_instance3 = dev_deployment_node.add_container(container3)
+    system_instance = dev_deployment_node.add_software_system(system4)
+
+    # The following live element instances should not affect the relationships of the
+    # development element instances
+    live_deployment_node = model.add_deployment_node(
+        "Deployment Node", environment="Live"
+    )
+    live_deployment_node.add_container(container1)
+    live_deployment_node.add_container(container2)
+    live_deployment_node.add_container(container3)
+    live_deployment_node.add_software_system(system4)
+
+    assert len(container_instance1.relationships) == 1
+    relationship = next(iter(container_instance1.relationships))
+    assert relationship.source is container_instance1
+    assert relationship.destination is container_instance2
+    assert relationship.description == "Uses 1"
+    assert relationship.technology == "Technology 1"
+    assert relationship.interaction_style == InteractionStyle.Synchronous
+    assert relationship.tags == set()
+
+    assert len(container_instance2.relationships) == 1
+    relationship = next(iter(container_instance2.relationships))
+    assert relationship.source is container_instance2
+    assert relationship.destination is container_instance3
+    assert relationship.description == "Uses 2"
+    assert relationship.technology == "Technology 2"
+    assert relationship.interaction_style == InteractionStyle.Asynchronous
+    assert relationship.tags == set()
+
+    assert len(container_instance3.relationships) == 1
+    relationship = next(iter(container_instance3.relationships))
+    assert relationship.source is container_instance3
+    assert relationship.destination is system_instance
+    assert relationship.description == "Uses"
+    assert relationship.technology == ""
+    assert relationship.interaction_style == InteractionStyle.Synchronous
+    assert relationship.tags == set()
+
+
+def test_not_replicating_doesnt_add_relationships(empty_model: Model):
+    """Ensure within the same environment, relationships are replicated."""
+    # Adapted from the Java ModelTests
+    model = empty_model
+    system1 = model.add_software_system("Software System 1")
+    container1 = system1.add_container("Container 1")
+
+    system2 = model.add_software_system("Software System 2")
+    container2 = system2.add_container("Container 2")
+
+    system3 = model.add_software_system("Software System 3")
+    container3 = system3.add_container("Container 3")
+
+    system4 = model.add_software_system("Software System 4")
+
+    container1.uses(
+        container2,
+        "Uses 1",
+        "Technology 1",
+        interaction_style=InteractionStyle.Synchronous,
+    )
+    container2.uses(
+        container3,
+        "Uses 2",
+        "Technology 2",
+        interaction_style=InteractionStyle.Asynchronous,
+    )
+    container3.uses(system4)
+
+    dev_deployment_node = model.add_deployment_node(
+        "Deployment Node", environment="Development"
+    )
+    container_instance1 = dev_deployment_node.add_container(
+        container1, replicate_relationships=False
+    )
+    container_instance2 = dev_deployment_node.add_container(
+        container2, replicate_relationships=False
+    )
+    container_instance3 = dev_deployment_node.add_container(
+        container3, replicate_relationships=False
+    )
+
+    assert container_instance1.relationships == set()
+    assert container_instance2.relationships == set()
+    assert container_instance3.relationships == set()

tests/unit/model/test_deployment_node.py

@@ -24,7 +24,7 @@ class MockModel:
 
     def __init__(self):
         """Initialize the mock, creating an empty node for tests."""
-        self.empty_node = DeploymentNode(name="Empty")
+        self.empty_node = DeploymentNode(name="Empty", environment="Live")
         self.empty_node.set_model(self)
         self.mock_element = MockElement("element")
 
@@ -133,6 +133,7 @@ def test_deployment_node_add_container(model_with_node):
     instance = node.add_container(container, replicate_relationships=False)
 
     assert instance.container is container
+    assert instance.environment == "Live"
     assert instance.model is model_with_node
     assert instance.parent is node
     assert instance in node.container_instances
@@ -160,12 +161,6 @@ def test_deployment_node_serialising_container(model_with_node):
     assert instance.parent is node2
 
 
-@pytest.mark.xfail(strict=True)
-def test_deployment_node_adding_container_replicating_relationships(model_with_node):
-    """Test replicating relationships when adding a container instance."""
-    raise AssertionError()  # Not implemented yet
-
-
 def test_deployment_node_add_software_system(model_with_node):
     """Test adding a software system to a node to create an instance."""
     node = model_with_node.empty_node
@@ -174,6 +169,7 @@ def test_deployment_node_add_software_system(model_with_node):
     instance = node.add_software_system(system, replicate_relationships=False)
 
     assert instance.software_system is system
+    assert instance.environment == "Live"
     assert instance.model is model_with_node
     assert instance.parent is node
     assert instance in node.software_system_instances
@@ -201,14 +197,6 @@ def test_deployment_node_serialising_software_system(model_with_node):
     assert instance.parent is node2
 
 
-@pytest.mark.xfail(strict=True)
-def test_deployment_node_adding_software_system_replicating_relationships(
-    model_with_node,
-):
-    """Test replicating relationships when adding a software system instance."""
-    raise AssertionError()  # Not implemented yet
-
-
 def test_deployment_node_add_infrastructure_node(model_with_node):
     """Test adding an infrastructure node to a deployment node."""
     node = model_with_node.empty_node