architecture: preface it with some diagrams

A picture says more than a thousand words, they say.

Signed-off-by: Johannes Schindelin <[email protected]>

Author: dscho

content/architecture.md

@@ -1,6 +1,83 @@
 ---
 title: The architecture of GitGitGadget
 ---
+
+The essence of GitGitGadget can be illustrated by this diagram
+
+```mermaid
+graph LR
+    user["user (contributor)"]
+    pr-repo["pr-repo (GitGitGadget-enabled GitHub repo)"]
+    GitGitGadget["GitGitGadget"]
+    mailing-list["mailing-list"]
+
+    user -->|"opens PR"| pr-repo
+
+    pr-repo -->|"slash commands"| GitGitGadget
+
+    GitGitGadget -->|"sends patch series"| mailing-list
+```
+
+Of course, when adding a couple of details, it gets quite a bit more complicated. For example, GitGitGadget needs write permissions on the `pr-repo`, to push the tagged patch series, and to store its state in Git notes. Most upstream projects do not like that, and therefore GitGitGadget works on a `pr-repo` which is a fork of an `upstream-repo`. However, a _read-only_ variant of GitGitGadget's GitHub App can be installed on the `upstream-repo`, in which case GitGitGadget _does_ handle PRs in the `upstream-repo` but the state and the tagged patch series still live in `pr-repo`.
+
+For testing purposes, there can also be `test-repo`, another fork of `upstream-repo` (but only the owner of the `test-repo` is allowed to use GitGitGadget there).
+
+GitGitGadget also needs access to the mailing list in the form of a [public-inbox](https://public-inbox.org/README.html) repository, to be able to mirror replies back to the PRs.
+
+
+```mermaid
+graph TD
+  user["user (contributor)"]
+  upstream-repo("upstream-repo (authoritative project repo)")
+  pr-repo("pr-repo (GitGitGadget-enabled GitHub repo)")
+  test-repo("test-repo (fork that is strictly for testing, optional)")
+  GitGitGadget{"GitGitGadget"}
+  gitgitgadget-github-app-repo("gitgitgadget-github-app-repo")
+  azure-function
+  gitgitgadget-workflows-repo("gitgitgadget-workflows-repo")
+  gitgitgadget-repo("gitgitgadget-repo")
+  mailing-list["mailing-list"]
+  mailing-list-repo("mailing-list-repo")
+  mailing-list-repo-mirror("mailing-list-repo-mirror")
+
+  user -->|"opens PR"| pr-repo
+  user -->|"opens PR"| upstream-repo
+  user -->|"opens PR"| test-repo
+
+  upstream-repo -->|"GitGitGadget syncs branches to"| pr-repo
+
+  pr-repo -->|"slash commands"| GitGitGadget
+  upstream-repo -->|"slash commands (if App installed)"| GitGitGadget
+  test-repo -->|"slash commands (only test-repo owner allowed)"| GitGitGadget
+
+  GitGitGadget -->|"sends patch series"| mailing-list
+  GitGitGadget -->|"runs in"| gitgitgadget-workflows-repo
+  gitgitgadget-workflows-repo -->|"uses GitHub Actions from"| gitgitgadget-repo
+
+  pr-repo -->|"webhook events"| azure-function
+  upstream-repo -->|"webhook events (if App installed)"| azure-function
+  test-repo -->|"webhook events"| azure-function
+  mailing-list-repo-mirror -->|"webhook events"| azure-function
+
+  gitgitgadget-github-app-repo -->|"deploys to"| azure-function
+
+  azure-function -->|"triggers"| GitGitGadget
+
+  mailing-list -->|public-inbox| mailing-list-repo
+  mailing-list-repo -->|"GitGitGadget syncs to"| mailing-list-repo-mirror
+  mailing-list-repo-mirror -->|"GitGitGadget mirrors replies to"| pr-repo
+  mailing-list-repo-mirror -->|"GitGitGadget mirrors replies to (if App installed)"| upstream-repo
+  mailing-list-repo-mirror -->|"GitGitGadget mirrors replies to"| test-repo
+
+  %% Some styling
+  classDef user fill:#77f;
+  class user user
+  classDef repo fill:#fb7,stroke:#333,stroke-width:2px;
+  class gitgitgadget-github-app-repo,gitgitgadget-workflows-repo,gitgitgadget-repo,mailing-list-repo,mailing-list-repo-mirror repo
+  classDef pr fill:#ea6,stroke:#333,stroke-width:4px;
+  class upstream-repo,pr-repo,test-repo pr
+```
+
 # How does GitGitGadget process user comments on PRs?
 
 GitGitGadget is implemented as a GitHub App (with the very imaginative name ["GitGitGadget"](https://github.com/apps/gitgitgadget)), which means that a webhook is called on certain events, such as new PR comments on PRs (e.g. `issue_comment`).

layouts/_default/baseof.html

@@ -12,4 +12,10 @@
     {{ .Content }}
     {{ end }}
   </body>
+{{ if .Store.Get "hasMermaid" }}
+  <script type="module">
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
+    mermaid.initialize({ startOnLoad: true });
+  </script>
+{{ end }}
 </html>

layouts/_markup/render-codeblock-mermaid.html

@@ -0,0 +1,4 @@
+<pre class="mermaid">
+  {{ .Inner | htmlEscape | safeHTML }}
+</pre>
+{{ .Page.Store.Set "hasMermaid" true }}