diff --git a/docs/syntax/architecture.md b/docs/syntax/architecture.md
index f0f0e9ac76..e86b2ca923 100644
--- a/docs/syntax/architecture.md
+++ b/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`.
diff --git a/packages/mermaid/src/docs/syntax/architecture.md b/packages/mermaid/src/docs/syntax/architecture.md
index 3fc5629f4d..b124ed7cdb 100644
--- a/packages/mermaid/src/docs/syntax/architecture.md
+++ b/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`.