Skip to content

0004: Representing Architecture Visually

STATUS

Proposed

CONTEXT

Visual representations are critical for rich understanding of an architecture. As we begin to use ADRs to capture architectural decisions we need a standard visualization solution to include with ADRs.

Considered Options

  • Capture architecture in Mermaid diagrams
  • Capture architecture in Miro
  • Capture architecture in Mermaid or Miro, with a preference for Mermaid [CHOSEN]

DECISION

There are two overarching objectives in making this decision: providing version control of illustrations, while also supporting agile architecture design. Mermaid diagrams have the advantage of being under version control, where we get all the benefits of GitHub, including PR comments and approvals. On the other hand, Mermaid diagrams can be time-consuming to develop, and some architectures are too complicated to be effectively represented with Mermaid.

We will try to have our cake and eat it too. Developers should favor using Mermaid diagrams, although, given the right conditions, diagramming in Miro is acceptable. Miro should be used when the architecture design is under rapid and frequent iteration, or when the architecture is overly complex.

CONSEQUENCES

All architecturally significant diagrams shall be submitted to this repository in the form of an ADR.

When proposing a new architecture, or capturing an existing architecture, engineers shall diagram the architecture with Mermaid if possible. This diagram will be included in the body of the ADR.

When Miro is needed, the Miro document should be linked to in the ADR, with a specific date/time version noted. (Miro does provide limited version history.)

Risks

There are certainly downsides to this approach. We risk having an inconsistent approach to documentation.

NOTES

References

Original Author

Ron White

Approval date

Approved by

Appendix