docs: Add ARCHITECTURE.md with diagram of components #615
Conversation
cliffmccarthy
commented
Aug 11, 2025
cliffmccarthy
commented
- 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
|
The current revision is a rough draft, and will probably be revised further as I study the code more. |
ARCHITECTURE.md
Outdated
| @@ -0,0 +1,37 @@ | |||
| This diagram shows components of the chatmail server: | |||
There was a problem hiding this comment.
Please qualify this sentence that's it's a draft overview as of mid August 2025.
There was a problem hiding this comment.
Thanks for the review! I updated the text as you suggested. I also added labels to some of the arrows to indicate the ports and sockets that the components communicate by.
- 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
- Suggested in review by hpk42.
cliffmccarthy
force-pushed
the
architecture-doc
branch
from
c0f630f to
0c1adff
Compare
There was a problem hiding this comment.
This is a great start, the only missing things I can think of are opendkim and the lastlogin service, but we can also merge it as it is and add them later :)
I added some suggestions, which would make more sense for me - but as this diagram is not so I can understand it, but for newcomers, I'd leave it to you which you want to adapt :)
For others looking at this, a preview is at https://github.com/cliffmccarthy/chatmail-relay/blob/architecture-doc/ARCHITECTURE.md
| chatmail-metrics --> /var/www/html; | ||
| acmetool --> certs; | ||
| acmetool --> acmetool-redirector; | ||
| acmetool-redirector --> certs; |
There was a problem hiding this comment.
| acmetool-redirector --> certs; | |
| acmetool-redirector --> nginx; |
I would argue that acmetool-redirector doesn't actually have much to do with certs, and mostly just redirects traffic to nginx?
| acmetool --> certs; | ||
| acmetool --> acmetool-redirector; | ||
| acmetool-redirector --> certs; | ||
| nginx --> /var/www/html; |
There was a problem hiding this comment.
| nginx --> /var/www/html; | |
| nginx --> |8443|/var/www/html; |
We could include that port 8443 is needed to show the webroot directory :)
| acmetool-redirector --> certs; | ||
| nginx --> /var/www/html; | ||
| nginx --> certs; | ||
| nginx --> newemail.py; |
There was a problem hiding this comment.
| nginx --> newemail.py; | |
| nginx --> |8443|newemail.py; |
same for newemail.py :)
| acmetool --> acmetool-redirector; | ||
| acmetool-redirector --> certs; | ||
| nginx --> /var/www/html; | ||
| nginx --> certs; |
There was a problem hiding this comment.
| nginx --> certs; | |
| certs --> nginx; |
And one could argue that nginx is dependent on the certs, not the other way round.
| nginx --> |993|dovecot; | ||
| autoconfig.xml --> postfix; | ||
| autoconfig.xml --> dovecot; | ||
| postfix --> certs; |
There was a problem hiding this comment.
| postfix --> certs; | |
| certs --> postfix; |
same for postfix...
| postfix --> |10080,10081|filtermail; | ||
| postfix --> echobot; | ||
| postfix --> |doveauth.socket|doveauth; | ||
| dovecot --> certs; |
There was a problem hiding this comment.
| dovecot --> certs; | |
| certs --> dovecot; |
...and dovecot ;)
| cron --> acmetool; | ||
| cron --> chatmail-metrics; | ||
| chatmail-metrics --> /var/www/html; | ||
| acmetool --> certs; |
There was a problem hiding this comment.
| acmetool --> certs; | |
| acmetool --> /var/lib/acme; |
For /home/vmail and /var/www/html we also talk about the path, because they contain state... we could do that for the certs as well :) that would make it clearer what to backup/manage. maybe TLS certs /var/lib/acme, Users /home/vmail, and Website /var/www/html? That would make it more obvious what the paths contain.
|
Let me know what changes you want to include, then I'll merge this :) |
|
Thanks for all the review feedback! I will submit a new revision in the next day or two. |
