From 2de8b155c2783562882d19f1499bd70444513fa6 Mon Sep 17 00:00:00 2001
From: cliffmccarthy <16453869+cliffmccarthy@users.noreply.github.com>
Date: Mon, 18 Aug 2025 12:09:03 -0500
Subject: [PATCH] docs: Rework architecture diagram based on review feedback

- Implemented changes suggested in review by missytake:
    - Removed relation between acmetool-redirector and certs.
    - Added internal nginx listening on port 8443.
    - Changed direction of arrows between certs and the services that
      use them.  This makes the arrow show the direction of
      information flow, rather than a "depends on" relation.
    - For filesystem paths, added a descriptive name to the node.
- Replaced most arrows with plain lines, to simply show that a
  relationship exists between the two nodes.  This also reduces visual
  clutter, since the graph is pretty dense with information already.
- Split nginx and certs into two nodes, to reduce entanglement in the
  graph.  These "linked" nodes are given a different shape and filled
  with a different colour, to highlight the fact that they are the
  same node.
- Revised text about the meaning of edges in the graph.
---
 ARCHITECTURE.md | 74 ++++++++++++++++++++++++++++---------------------
 1 file changed, 43 insertions(+), 31 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index e6b188e4..a4191cae 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -3,36 +3,48 @@ overview as of mid-August 2025:
 
 ```mermaid
 graph LR;
-    cmdeploy --> sshd;
-    cron --> expunge;
-    cron --> acmetool;
-    cron --> chatmail-metrics;
-    chatmail-metrics --> /var/www/html;
-    acmetool --> certs;
-    acmetool --> acmetool-redirector;
-    acmetool-redirector --> certs;
-    nginx --> /var/www/html;
-    nginx --> certs;
-    nginx --> newemail.py;
-    nginx --> |465|postfix;
-    nginx --> autoconfig.xml;
-    nginx --> |993|dovecot;
-    autoconfig.xml --> postfix;
-    autoconfig.xml --> dovecot;
-    postfix --> certs;
-    postfix --> /home/vmail/mail;
-    postfix --> |10080,10081|filtermail;
-    postfix --> echobot;
-    postfix --> |doveauth.socket|doveauth;
-    dovecot --> certs;
-    dovecot --> |doveauth.socket|doveauth;
-    dovecot --> /home/vmail/mail;
-    dovecot --> |metadata.socket|chatmail-metadata;
-    doveauth --> /home/vmail/mail;
-    expunge --> /home/vmail/mail;
-    chatmail-metadata --> iroh-relay;
+    cmdeploy --- sshd;
+    letsencrypt --- |80|acmetool-redirector;
+    acmetool-redirector --- |443|nginx-right(["`nginx
+    (external)`"]);
+    nginx-external --- |465|postfix;
+    nginx-external(["`nginx
+    (external)`"]) --- |8443|nginx-internal["`nginx
+    (internal)`"];
+    nginx-internal --- website["`Website
+    /var/www/html`"];
+    nginx-internal --- newemail.py;
+    nginx-internal --- autoconfig.xml;
+    certs-nginx[("`TLS certs
+    /var/lib/acme`")] --> nginx-internal;
+    cron --- chatmail-metrics;
+    cron --- acmetool;
+    cron --- expunge;
+    chatmail-metrics --- website;
+    acmetool --> certs[("`TLS certs
+    /var/lib/acme`")];
+    nginx-external --- |993|dovecot;
+    autoconfig.xml --- postfix;
+    autoconfig.xml --- dovecot;
+    postfix --- echobot;
+    postfix --- |10080,10081|filtermail;
+    postfix --- users["`User data
+    home/vmail/mail`"];
+    postfix --- |doveauth.socket|doveauth;
+    dovecot --- |doveauth.socket|doveauth;
+    dovecot --- users;
+    dovecot --- |metadata.socket|chatmail-metadata;
+    doveauth --- users;
+    expunge --- users;
+    chatmail-metadata --- iroh-relay;
+    certs-nginx --> postfix;
+    certs-nginx --> dovecot;
+    style certs fill:#ff6;
+    style certs-nginx fill:#ff6;
+    style nginx-external fill:#fc9;
+    style nginx-right fill:#fc9;
 ```
 
-(Arrows in this diagram do not have a specific formal meaning; they
-signify "depends on", or "uses", or "sends data to", or just "relates
-to".)
+The edges in this graph should not be taken too literally; they
+reflect some sort of communication path or dependency relationship
+between components of the chatmail server.