🧭 Diagrams as Code

[bagg3rs]

User Story

As a Platform Engineer I want long-lived diagrams stored as code in the product or services repository. So that diagrams are versioned, stored as text (searchable.. actionable, diffed easily, integration for CI/CD / automation and in one repository.

Value / Purpose

• All the products we deploy are stored as code. In every version, we can integrate, apply metadata. This is not true of diagrams of static tools exporting PDF/JPEG/PNG. These ultimately end up dead e.g. not a true reflection of whats deployed so require further investigations (time is money)) and the source files (to actually update the thing) of the diagram are 100% absent 👿 and the source missing 🪦...☠️.
• Gain a structured way of storing these stories/maps for the things we have created for future you and others.
• Can we be more DRY(Don't Repeat Yourself)😐? With Mermaid/UML/Visio/Draw.io you need to create multiple diagrams to show various levels of detail or other sections. Changing Visio/Draw.io can be problematic (I need to add another box.... shuffles endless lines around..., this results in the diagrams never being touched after the project is completed usually when whoever created them has gone.

Useful Contacts

Rich B

Additional Information

• Must be easy for all team members! We can have a play-off on learn tech afternoon.
• You can export this AWS example code to see the language differences e.g. mermaid, dot, UML etc.
• https://github.com/structurizr/dsl provides a context-based (C4 diagramming language) rather than named boxes and arrows.
• HMPPS and LLA use structurizr AWS example 🤔 discussion: is this a problem if just creating simpler deployment diagrams vs the added complexity of e.g. using structurizr is there... value in the effort.
• Diagrams @Gary-H9 as Code lets you draw the cloud system architecture in Python code. nice AWS example
• Mermaid MoJO-DNS example
• Backstage is worth watching, great job of rendering code inside the repo into diagrams.
• Excalidraw - we are using for our C4 diagrams already see #580

Definition of Done

• [ ] Discussed as team
• [ ] README has been updated
• [ ] User docs on how to diagram have been created
• [ ] Another team member has reviewed
• [ ] Tests are green

[Gary-H9]

Team has elected to use Diagrams for the time being. Should we need to pivot we will revisit this ticket.

[bagg3rs]

Have transferred this issue to look at IF we should look at using e.g. Strcuturizer

[github-actions[bot]]

This issue is being marked as stale because it has been open for 60 days with no activity. Remove stale label or comment to keep the issue open.

[github-actions[bot]]

This issue is being closed because it has been open for a further 7 days with no activity. If this is still a valid issue, please reopen it, Thank you!