Platform engineering is the discipline of designing and building toolchains and workflows that enable self-service capabilities for software engineering organizations in the cloud-native era.

Platform Engineering

<https://kroki.io/>
PlantUML
diagram as a code

Step 1. Use infrastructure as code and store in git. 

Step 2. Keep your docs and diagram as close to the code as you can. I have used <http://draw.io|draw.io> with drawio.png file extensions to visualize the architecture diagrams in markdown while still working with a good pull request process. The drawio.png file extension with the vscode plugin for <http://draw.io|draw.io> allows you to edit the file in <http://draw.io|draw.io> (no need to convert or export it as a png) and still be tracked nicely in git while even being visually rendered during PR process. Thus when a PR comes in to change the IaC, the reviewer should look at code, look for corresponding updates in the docs (markdown), and look for updated diagram. If something is missing, reviewer would request submitter to update their docs or diagram. It really comes down to a process that ensures docs/diagrams are updated whenever a change happens.

If you can integrate your IDP to render your markdown from the project directly, then anytime that markdown changes for docs, so will your IDP docs. If you separate the two....odds are something will be out of sync.

Thanks for the sharing your process. good insight about <http://draw.io|draw.io> usage.