This is just awesome and I consider such things (graphics, contributor guidance) a priority for documentation.
Unless there are strong reasons against this, it should immediately become a PR so we have more contributor eyes on it and a structured review process.
Right now we don’t seem to have mermaid rendering for Nixpkgs/NixOS manual, but we can still discuss this based on GitHub previews and decide later how to present the result. (Worst case just check in a static SVG and leave the source in a separate file, together with notes how to manually update.)
@drupol absolutely great job on the diagrams. They are incredibly helpful. I’ve been thinking these days how we could get them to the manuals as soon as possible.
Since you’re essentially introducing a new workflow to developing Nixpkgs/NixOS, part of a PR to add the first diagram should be documentation how to maintain it. So far, we’re utterly bad at this in the Nix ecosystem, and this would be an opportunity to improve and set a good example.
I also have a few things I would like to discuss about presentation, and found myself incapable of suggesting changes directly, because I’m absolutely not used to plantUML.
Another ridiculous problem is that having a separate GitHub project prevents me to add comments or suggestions to existing code without jumping through the PR hoops.
More overviews and illustrations are key to improving user and contributor onboarding. I wrote you a DM to schedule a chat.