RFC: add architecture documentation inspired by the C4 model approach

[LarsArtmann]

What does this PR aim to accomplish?:

I was searching for a architecture diagram of pihole's internals. Since I was unable to find one, I created this.

Images

How does this PR accomplish the above?:

The PR adds a new architecture.md file in the main folder. The new file includes multiple mermaid sections that can be easily rendered into good looking diagrams.

Open Issue:

I did not manage to test my changes. mkdocs build and mkdocs serve do not work for because of issue(s) with the template.

Note

My understanding of the whole projects architecture is limited, it is very possible some of the diagrams have mistakes. I do think it is a good start though. Input or changes are very welcome!

---

• [X] I have read the above and my PR is ready for review. Check this box to confirm

[netlify[bot]]

✅ Deploy Preview for pihole-docs ready!

Name	Link
🔨 Latest commit	067fff4058e43e0d2c9be6002cbfeffb67b97db5
🔍 Latest deploy log	https://app.netlify.com/projects/pihole-docs/deploys/6828f08bce77ac0008dc0027
😎 Deploy Preview	https://deploy-preview-1241--pihole-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[LarsArtmann]

Looking at: the preview, to make this truly valuable, we would need to

1. add a mermaid.js parser or
2. use SVGs or PNGs instead.

I would tend to option 1. Does anybody know enough about the building process to help with the implementation of mermaid.js parser support?

[yubiuser]

Does anybody know enough about the building process to help with the implementation of mermaid.js parser support?

Should be pretty simple: https://squidfunk.github.io/mkdocs-material/reference/diagrams/

[yubiuser]

Before you invest more time in this PR: While it looks interesting at first to see the inner workings depicted, I'm not sure how much benefit users get from this. If I had no clue how Pi-hole works, the figures might not help much as they are very complex (as is Pi-hole). My biggest concern with those images: they will need updates every time something changes. And we will likely forget about this.

[LarsArtmann]

Before you invest more time in this PR: While it looks interesting at first to see the inner workings depicted, I'm not sure how much benefit users get from this. If I had no clue how Pi-hole works, the figures might not help much as they are very complex (as is Pi-hole).

These diagrams are aimed at potential contributors, not general users, to aid understanding of Pi-hole's internals.

My biggest concern with those images: they will need updates every time something changes. And we will likely forget about this.

A very reasonable concern. We could just add a notice stating the diagrams may not be up-to-date, including the last update date, to manage maintenance expectations.

Place this under Contributing rather than General would provide better context.

[rdwebdesign]

I think your suggestion is interesting, but the diagrams seems too complex. In my opinion, only users that already understand how Pi-hole works will understand the images.

We could just add a notice stating the diagrams may not be up-to-date

Sometimes we forget to update some things, but adding information we already know will be outdated is a bad practice.

[LarsArtmann]

Sometimes we forget to update some things, but adding information we already know will be outdated is a bad practice.

Good point. We don't need to include all of the charts I suggested. I can see how charts 1 and 2 could change, but the 3rd (flow) chart should remain fairly stable, shouldn't it?