From bcbbe4f751b2eca80180c632c3967d4fd0f4784c Mon Sep 17 00:00:00 2001 From: cliffmccarthy <16453869+cliffmccarthy@users.noreply.github.com> Date: Sun, 10 Aug 2025 11:27:43 -0500 Subject: [PATCH 1/3] docs: Add ARCHITECTURE.md with diagram of components - For starters, this file is just a diagram of components of a chatmail server. In the future, this document can grow into a more complete description of the architecture of the server, the deployment process, and the design intent behind what is and isn't in the code base. - The name ARCHITECTURE.md is inspired by this article, which also has good suggestions about what to put in the file: https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html --- ARCHITECTURE.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 00000000..7d3b2b9c --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,37 @@ +This diagram shows components of the chatmail server: + +```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; +``` + +(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".) From 0c1adff9ed0df3ad18d8ee0fc4bcf5b30b32eb16 Mon Sep 17 00:00:00 2001 From: cliffmccarthy <16453869+cliffmccarthy@users.noreply.github.com> Date: Fri, 15 Aug 2025 18:04:30 -0500 Subject: [PATCH 2/3] docs: Indicate draft status in ARCHITECTURE.md - Suggested in review by hpk42. --- ARCHITECTURE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 7d3b2b9c..e6b188e4 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,4 +1,5 @@ -This diagram shows components of the chatmail server: +This diagram shows components of the chatmail server; this is a draft +overview as of mid-August 2025: ```mermaid graph LR; From 41b859fb24c875a2b4a61376249eb426e444abf6 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 3/3] 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.