[Architecture/fix] Throw explicit error for invalid configuration causing overlapping nodes

.changeset/bright-goats-clap.md

@@ -0,0 +1,5 @@
+---
+'mermaid': patch
+---
+
+fix: added documentation & error handling to overlapping nodes of architecture diagrams

cypress/integration/rendering/architecture.spec.ts

@@ -223,6 +223,23 @@ describe.skip('architecture diagram', () => {
       `
     );
   });
+
+  it('should render an error due to overlapping nodes', () => {
+    // #6120
+    imgSnapshotTest(
+      `architecture-beta
+            group clients(cloud)[Clients]
+            group vercel_cloud(cloud)[Vercel cloud]
+
+            service mobile_app(internet)[Mobile app] in clients
+            service web_app(internet)[Web app] in clients
+            service middleware(middleware)[Middleware] in vercel_cloud
+
+            mobile_app:R -- L:middleware
+            web_app:R -- L:middleware
+      `
+    );
+  });
 });
 
 // Skipped as the layout is not deterministic, and causes issues in E2E tests.

docs/syntax/architecture.md

@@ -191,6 +191,64 @@ architecture-beta
     bottom_gateway:T -- B:junctionRight
 ```
 
+## Limitations
+
+Due to underlying limitations in the rendering engine, there are a couple things to keep in mind when designing your Architecture diagrams.
+
+### One edge per side
+
+Only one edge may come out of each side of a node. If multiple edges are needed, junctions should be used.
+
+**Invalid** (error logged to console):
+
+```mermaid-example
+architecture-beta
+    service nodeA(internet)[Node A]
+    service nodeB1(internet)[Node B1]
+    service nodeB2(middleware)[Node B2]
+
+    nodeA:R --> L:nodeB1
+    nodeA:R --> L:nodeB2
+```
+
+```mermaid
+architecture-beta
+    service nodeA(internet)[Node A]
+    service nodeB1(internet)[Node B1]
+    service nodeB2(middleware)[Node B2]
+
+    nodeA:R --> L:nodeB1
+    nodeA:R --> L:nodeB2
+```
+
+**Valid**:
+
+```mermaid-example
+architecture-beta
+    service nodeA(internet)[Node A]
+    service nodeB1(server)[Node B1]
+    service nodeB2(server)[Node B2]
+
+    junction aToB
+
+    nodeA:R --> L:aToB
+    aToB:T --> B:nodeB1
+    aToB:B --> T:nodeB2
+```
+
+```mermaid
+architecture-beta
+    service nodeA(internet)[Node A]
+    service nodeB1(server)[Node B1]
+    service nodeB2(server)[Node B2]
+
+    junction aToB
+
+    nodeA:R --> L:aToB
+    aToB:T --> B:nodeB1
+    aToB:B --> T:nodeB2
+```
+
 ## Icons
 
 By default, architecture diagram supports the following icons: `cloud`, `database`, `disk`, `internet`, `server`.

packages/mermaid/src/diagrams/architecture/architectureDb.ts

@@ -42,6 +42,7 @@ const state = new ImperativeState<ArchitectureState>(() => ({
   groups: {},
   edges: [],
   registeredIds: {},
+  usedEdges: {},
   config: DEFAULT_ARCHITECTURE_CONFIG,
   dataStructures: undefined,
   elements: {},
@@ -203,6 +204,21 @@ const addEdge = function ({
     title,
   };
 
+  state.records.usedEdges[lhsId] ??= {};
+  state.records.usedEdges[rhsId] ??= {};
+  if (state.records.usedEdges[lhsId][lhsDir]) {
+    throw new Error(
+      `There is already an existing edge coming out of side [${lhsDir}] for service [${lhsId}] to [${rhsId}]. Please use junctions to connect multiple services to one side.`
+    );
+  }
+  if (state.records.usedEdges[rhsId][rhsDir]) {
+    throw new Error(
+      `There is already an existing edge coming out of side [${rhsDir}] for service [${rhsId}] to [${lhsId}]. Please use junctions to connect multiple services to one side.`
+    );
+  }
+  state.records.usedEdges[lhsId][lhsDir] = true;
+  state.records.usedEdges[rhsId][rhsDir] = true;
+
   state.records.edges.push(edge);
   if (state.records.nodes[lhsId] && state.records.nodes[rhsId]) {
     state.records.nodes[lhsId].edges.push(state.records.edges[state.records.edges.length - 1]);

packages/mermaid/src/diagrams/architecture/architectureTypes.ts

@@ -291,6 +291,7 @@ export interface ArchitectureState extends Record<string, unknown> {
   groups: Record<string, ArchitectureGroup>;
   edges: ArchitectureEdge[];
   registeredIds: Record<string, 'node' | 'group'>;
+  usedEdges: Record<string, Record<string, boolean>>;
   dataStructures?: ArchitectureDataStructures;
   elements: Record<string, D3Element>;
   config: ArchitectureDiagramConfig;

packages/mermaid/src/docs/syntax/architecture.md

@@ -153,6 +153,41 @@ architecture-beta
     bottom_gateway:T -- B:junctionRight
 ```
 
+## Limitations
+
+Due to underlying limitations in the rendering engine, there are a couple things to keep in mind when designing your Architecture diagrams.
+
+### One edge per side
+
+Only one edge may come out of each side of a node. If multiple edges are needed, junctions should be used.
+
+**Invalid** (error logged to console):
+
+```mermaid-example
+architecture-beta
+    service nodeA(internet)[Node A]
+    service nodeB1(internet)[Node B1]
+    service nodeB2(middleware)[Node B2]
+
+    nodeA:R --> L:nodeB1
+    nodeA:R --> L:nodeB2
+```
+
+**Valid**:
+
+```mermaid-example
+architecture-beta
+    service nodeA(internet)[Node A]
+    service nodeB1(server)[Node B1]
+    service nodeB2(server)[Node B2]
+
+    junction aToB
+
+    nodeA:R --> L:aToB
+    aToB:T --> B:nodeB1
+    aToB:B --> T:nodeB2
+```
+
 ## Icons
 
 By default, architecture diagram supports the following icons: `cloud`, `database`, `disk`, `internet`, `server`.