From ac48bb4968f5cc4dd117364d0ff20414a4badc47 Mon Sep 17 00:00:00 2001
From: deltamarnix <150045289+deltamarnix@users.noreply.github.com>
Date: Fri, 10 Nov 2023 15:54:20 +0100
Subject: [PATCH] C4 diagrams (#770)

Add diagrams for C4 model showing the different components for ribasim,
the preprocessing API, and the QGIS plugin.

We could go even further and make a detailed diagram of the different
modules that are connected to each other. But these diagrams already
give an overview of the components that are involved in the system.

---------

Co-authored-by: Martijn Visser <mgvisser@gmail.com>
---
 docs/assets/c4_component_ribasim.mmd | 39 ++++++++++++++++++++++++++++
 docs/assets/c4_system.mmd            | 32 +++++++++++++++++++++++
 docs/core/index.qmd                  |  5 ++++
 docs/index.qmd                       |  5 ++++
 4 files changed, 81 insertions(+)
 create mode 100644 docs/assets/c4_component_ribasim.mmd
 create mode 100644 docs/assets/c4_system.mmd

diff --git a/docs/assets/c4_component_ribasim.mmd b/docs/assets/c4_component_ribasim.mmd
new file mode 100644
index 000000000..5b751e62a
--- /dev/null
+++ b/docs/assets/c4_component_ribasim.mmd
@@ -0,0 +1,39 @@
+flowchart TB
+modeler([Modeler]):::user
+
+api["Ribasim Python\n[python]"]:::system
+modeler-->|prepare model|api
+
+subgraph ribasimBoundary[Ribasim]
+    ribasim["Ribasim.jl\n[julia]"]:::system
+    libribasim["libribasim\n[julia + python + BMI]"]:::system
+    cli["Ribasim CLI\n[julia]"]:::system
+    cli-->ribasim
+    libribasim-->ribasim
+end
+modeler-->|start|cli
+modeler-->|coupled simulation|libribasim
+
+subgraph qgisBoundary[QGIS]
+    QGIS[QGIS Application]:::system_ext
+    qgisPlugin["Ribasim QGIS plugin\n[python]"]:::system
+    QGIS-->qgisPlugin
+end
+modeler-->|prepare model|qgisBoundary
+
+model[("input model data\n[toml + geopackage + arrow]")]:::system
+qgisPlugin-->|read/write|model
+api-->|read/write|model
+ribasim-->|simulate|model
+
+output[("simulation output\n[arrow]")]:::system
+ribasim-->|write|output
+
+class qgisBoundary,ribasimBoundary boundary
+
+%% class definitions for C4 model
+classDef default stroke-width:1px,stroke:white,color:white
+classDef system fill:#1168bd
+classDef user fill:#08427b
+classDef system_ext fill:#999999
+classDef boundary fill:transparent,stroke-dasharray:5 5,stroke:black,color:black
diff --git a/docs/assets/c4_system.mmd b/docs/assets/c4_system.mmd
new file mode 100644
index 000000000..7a40986fa
--- /dev/null
+++ b/docs/assets/c4_system.mmd
@@ -0,0 +1,32 @@
+flowchart TB
+modeler([Modeler]):::user
+
+api["Ribasim Python\n[python]"]:::system
+modeler-->|prepare model|api
+
+ribasim["Ribasim\n[julia]"]:::system
+modeler-->|start|ribasim
+
+subgraph qgisBoundary[QGIS]
+    QGIS[QGIS Application]:::system_ext
+    qgisPlugin["Ribasim QGIS plugin\n[python]"]:::system
+    QGIS-->qgisPlugin
+end
+modeler-->|prepare model|qgisBoundary
+
+model[("input model data\n[toml + geopackage + arrow]")]:::system
+qgisPlugin-->|read/write|model
+api-->|read/write|model
+ribasim-->|simulate|model
+
+output[("simulation results\n[arrow]")]:::system
+ribasim-->|write|output
+
+class qgisBoundary boundary
+
+%% class definitions for C4 model
+classDef default stroke-width:1px,stroke:white,color:white
+classDef system fill:#1168bd
+classDef user fill:#08427b
+classDef system_ext fill:#999999
+classDef boundary fill:transparent,stroke-dasharray:5 5,stroke:black,color:black
diff --git a/docs/core/index.qmd b/docs/core/index.qmd
index 407dd2bf7..daeb53b2b 100644
--- a/docs/core/index.qmd
+++ b/docs/core/index.qmd
@@ -11,3 +11,8 @@ The core is implemented in the [Julia programming language](https://julialang.or
 can be found in the [Ribasim repository](https://github.com/Deltares/Ribasim) under the
 `core/` folder. For developers we also advise to read the
 [developer documentation](../contribute/core.qmd).
+
+```{mermaid}
+%%| file: ../assets/c4_component_ribasim.mmd
+%%| fig-cap: "Component overview of Ribasim"
+```
diff --git a/docs/index.qmd b/docs/index.qmd
index 8597df9a7..02a595d70 100644
--- a/docs/index.qmd
+++ b/docs/index.qmd
@@ -44,6 +44,11 @@ Currently only Windows builds for `ribasim_cli.zip` are available.
 
 See [Usage](core/usage.qmd) for more information.
 
+```{mermaid}
+%%| file: assets/c4_system.mmd
+%%| fig-cap: "System overview of Ribasim"
+```
+
 # Status
 
 The initial focus is on being able to