doc(mediator): add C4 diagrams (#49)

* doc(mediator): add context/container/component C4 diagrams * doc(mediator): update description * doc(mediator): use collections and not tables
hyperledger · Apr 30, 2024 · f3db2b6 · f3db2b6
1 parent b00b24f
commit f3db2b6
Show file tree

Hide file tree

Showing 5 changed files with 90 additions and 0 deletions.
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
@@ -0,0 +1,37 @@
+# System Architecture
+
+This document provides an overview of the system architecture for the Atala PRISM Mediator.
+
+## System Context Diagram
+
+The system context diagram illustrates the high-level interactions and dependencies of the Atala PRISM Mediator with
+external components, mainly cloud and edge agents.
+
+![](diagrams/mediator-context.png)
+
+## Container Diagram
+
+The container diagram depicts the internal containers/runnables and their relationships within the Atala PRISM Mediator.
+
+![](diagrams/mediator-container.png)
+
+### Mediator Agent Component Diagram
+
+The Mediator Agent handles the communication and coordination tasks of the Atala PRISM Mediator.
+
+- **DIDComm v2 Handler**: This component supports various protocols such as BasicMessage 2.0, MediatorCoordination 2.0,
+  Pickup 3.0, and TrustPing 2.0. It communicates with external systems via HTTP.
+
+- **QR Code Web App**: This component is responsible for displaying a QR code containing an OOB invitation that can be
+  scanned by an edge agent mobile application to initiate a mediation request with the mediator.
+
+![](diagrams/mediator-component.png)
+
+### Mediator Database
+
+The Mediator Database stores data related to the Atala PRISM Mediator. It contains the following collection:
+
+- **User Accounts**: for storing user account information of mediated agents.
+
+- **Message Items**: for storing messages sent by edge and cloud agents.
+
diff --git a/docs/architecture/diagrams/mediator-component.png b/docs/architecture/diagrams/mediator-component.png
diff --git a/docs/architecture/diagrams/mediator-container.png b/docs/architecture/diagrams/mediator-container.png
diff --git a/docs/architecture/diagrams/mediator-context.png b/docs/architecture/diagrams/mediator-context.png
diff --git a/docs/architecture/structurizr/workspace.dsl b/docs/architecture/structurizr/workspace.dsl
@@ -0,0 +1,53 @@
+workspace {
+
+    model {
+        agent = softwareSystem "Cloud / Edge Agent" "" "External"
+
+        enterprise "Atala" {
+            atalaPrismMediator = softwareSystem "Atala PRISM Mediator" {
+                mediatorAgent = container "Mediator Agent" {
+                    didCommHandler = component "DIDComm v2 Handler" "Supported protocols:\nBasicMessage 2.0\nMediatorCoordination 2.0\nPickup 3.0\nTrustPing 2.0" "ZIO HTTP" {
+                        agent -> this "Sends and receives messages" "HTTPS"
+                    }
+
+                    webapp = component "QR Code Web App" "" "Scala.js" {
+                        agent -> this "Scans mediation OOB invitation\n(QR code)" "HTTPS"
+                    }
+                }
+                db = container "Mediator Database" "Tables:\nUser Accounts\nMessages Items" "MongoDB" "Database" {
+                    didCommHandler -> this "Reads from and writes to"
+                }
+            }
+        }
+    }
+
+    views {
+        systemContext atalaPrismMediator {
+            include *
+            autolayout tb
+        }
+
+        container atalaPrismMediator {
+            include *
+            autolayout tb
+        }
+
+        component mediatorAgent {
+            include *
+            autolayout tb
+        }
+
+        theme default
+
+        styles {
+            element "External" {
+                background #999999
+                color #ffffff
+            }
+            element "Database" {
+                shape Cylinder
+            }
+        }
+    }
+
+}