Authenticating...
Skip to main 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​