New Diagram: Architecture

[NicolasNewman]

📑 Summary

Architecture diagrams allows users to show relations between services

Resolves #5367

📏 Design Decisions

Parser

Terminology

• Service: a node within a diagram. Represents services such as from AWS, Azure, Docker, etc
• Group: a collection of related services (similar in presentation to subgraphs for other diagrams). This could be a VPC on AWS, different APIs which talk to one another, etc

Syntax

Currently, the syntax is defined as:

• Services are defined as service {id}({icon})[{title}] (in {group_name})?
• Groups are defined as group {id}[{title}] (in {group_id})?
• Edges are defined as {id_1} ( ( )?(L|R|T|B)--(L|R|T|B)( ) )? {id_2}

Once I transition from jison to Langium, I plan to add the following extensions:

• Groups: group {id}({icon})[{title}] (in {group_id})?
  • Allow icons to be used for group names
• Edges: {id_1} ( ( )?(L|R|T|B)-([{label}])-(L|R|T|B)( ) )? {id_2}
  • Allow edges to have a label
  • Allow forked edges traversing the XY axis (see Layout for more info). I've yet to decide on the syntax for this
• Services: service {id}( ({icon}) | ("{text}") )[{title}] (in {group_name})?
  • Allow text to be used for a service instead of an icon

Additionally, the syntax for groups (and potentially forked edges?) will be modified to better follow a declare then organize approach

Layout

• The positions of services are determined by specifying a required direction for an edge between the two
• Edges which traverse the X & Y axis (LT, RB, etc) are connected by two perpendicular lines
• Each service can only have one edge per side
• Internally, a spatial map of each service is maintained which specifies an (x,y) coordinate of where each service is in relation to one another ([0,1] is above [0,0]). This forces the layout to have a consistent grid like pattern

Comments

As mentioned in the issue, the LRTB syntax goes against the ethos of Mermaid. Additionally, while the spatial map creates very neatly organized layouts, it prevents users from having multiple edges going out of one side. Part of the reason I began designing it this way was to avoid this diagram type from essentially being a flowchart with icons.

Going forward, there's a few options that can fix this problem:

1. Make the LRTB syntax optional. If they aren't ever specified, don't use the spatial map for generating the constraints for fcose and let it figure things out on its own.
2. Keep the LRTB syntax required and instead add svg icon support to flowcharts. Ultimately the two diagram types are very similar in how they represent nodes and edges. My main reasoning for adding this new diagram type other then SVG support was for more precise control over node positioning like with block diagrams. I've already been using flowcharts to quickly mock up architecture diagrams before making something nicer in softwares like Lucidcharts.

No matter which option we choose, the LRTB syntax should be extended to:

1. Allow forked edges. This means one edge out the X/Y axis would split into more edges that would expand outwards in the opposite axis. This would solve the issue of being limited to only a max of 4 edges per service.

SVG Icons

SVG icons are currently created and accessed through helper functions inside of rendering-util/svgRegister.ts. A global object stores the mapping of icon names to IconResolvers defined as

type IconResolver = (
  parent: Selection<SVGGElement, unknown, Element | null, unknown>,
  width?: number
) => Selection<SVGGElement, unknown, Element | null, unknown>;

IconResolvers can easily be created through the helper function createIcon. This function takes the SVG code as a string along with the original resolution. It returns a CB function taking the element to inject the SVG into and optionally a different size to scale it by.

const createIcon = (icon: string, originalSize: number): IconResolver => {
  return (
    parent: Selection<SVGGElement, unknown, Element | null, unknown>,
    size: number = originalSize
  ) => {
    parent.html(`<g style="transform: scale(${size / originalSize})">${icon}</g>`);
    return parent;
  };
};

A few generic icons I've created are located in rendering-utils/svg/. Additional icons can be added through the new iconLibraries config option. The types in svgRegister.ts are now exported from mermaid.ts, allowing developers to create their own icon library packages.

// Example icon

// rendering-util/svg/database.ts
export default createIcon(
  `<g>
      <rect width="80" height="80" style="fill: #087ebf; stroke-width: 0px;"/>
     ...
</g>`,
  80
);

// rendering-util/svg/index.ts
const defaultIconLibrary: IconLibrary = {
  database: database,
  // ...
};

// index.html
mermaid.initialize({
  theme: 'base',
  startOnLoad: true,
  // This is just an example. It is already loaded by default within MermaidAPI.ts
  iconLibraries: [defaultIconLibrary],
  // ...
});

Alternatives

From conversations in the linked issue, ZenUML already handles SVG icons on their end. Upon furthur inspection, they rely on declaring an svg module which essentially resolves the imported SVG as a string. Since the end result of both of these approaches are the same (having the SVG code as a string), personally I think it's debatable if we want to go through with this extra step. The main con I foresee is that it'll add more work for people who want to make their own icon library package as they will need to setup the declarations themselves.

On a side note, it looks like ZenUML directly added the official AWS icons to their repo here. IANAL but the terms Amazon states are:

Customers and partners are permitted by AWS to use the resources below to create architecture diagrams

This may mean we can make official icon packs in seperate packages, or have them be lazy loaded as needed. Ultimately I'll leave that decision up to you as that isn't my area of specialties.

Todo

• Unit tests
• Documentation
• More generic default icons? If anyone has ideas let me know and I can put something together in Illustrator
• Convert parser from jison to Langium
• Implemented parser extensions
  • Edge labels
  • Icons as group names
  • Text instead of service icon
• Forked edges
• Edges between groups
• More control over styling

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🔖 targeted develop branch

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	48e6901
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/6638f197bf620e0008c09ff3
😎 Deploy Preview	https://deploy-preview-5452--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 1460 lines in your changes are missing coverage. Please review.

Project coverage is 5.55%. Comparing base (3ccfea8) to head (497712a).
Report is 86 commits behind head on develop.

❗ Current head 497712a differs from pull request most recent head 48e6901. Consider uploading reports for the commit 48e6901 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #5452      +/-   ##
==========================================
- Coverage     5.74%   5.55%   -0.20%     
==========================================
  Files          277     290      +13     
  Lines        41897   43345    +1448     
  Branches       489     528      +39     
==========================================
  Hits          2407    2407              
- Misses       39490   40938    +1448     

Flag	Coverage Δ
unit	5.55% <0.00%> (-0.20%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
.build/jsonSchema.ts	0.00% <0.00%> (ø)
.../mermaid/scripts/create-types-from-json-schema.mts	0.00% <0.00%> (ø)
...s/mermaid/src/diagram-api/diagram-orchestration.ts	0.00% <0.00%> (ø)
packages/mermaid/src/mermaid.ts	0.00% <0.00%> (ø)
packages/mermaid/src/mermaidAPI.ts	0.00% <0.00%> (ø)
...d/src/diagrams/architecture/architectureDiagram.ts	0.00% <0.00%> (ø)
packages/mermaid/src/rendering-util/svg/unknown.ts	0.00% <0.00%> (ø)
packages/mermaid/src/rendering-util/svg/index.ts	0.00% <0.00%> (ø)
...ackages/mermaid/src/rendering-util/svg/database.ts	0.00% <0.00%> (ø)
...ackages/mermaid/src/rendering-util/svg/internet.ts	0.00% <0.00%> (ø)
... and 9 more

... and 1 file with indirect coverage changes

[NicolasNewman]

@sidharthv96 Continuing our conversation from the issue, I commented on SVG loading and my thought process behind how the layout is handled. Let me know what your thoughts are.

Additionally, an example of what forked edges would look like once implemented:

Regarding multiple edges going into one side of a service, it's possible but I'll need to spend some time figuring out the cleanest way to implement that functionality. Ultimately I was planning on using forked edges to handle that scenario but after looking at your example the arrows can't be as neatly represented the same way through forked edges.

[NicolasNewman]

Here is where the renderer currently stands.

From a stylistic standpoint I'm considering:

1. shortening the edges so they don't overlap with the service label.
2. removing the rotation of the labels for Y/XY edges (or adding a config option)

Simple diagram with an icon in the group name

Groups within groups

90 degree edges

Edge Arrows

Edge Labels

[hemeroc]

Regarding the icons it would be awesome if it's possible to use any of those:

• https://ionic.io (MIT License)
• https://feathericons.com/ (MIT License)

Maybe they could be shipped as icon library? From a license PoV this should be okey and would immediately add many icons.

More generic default icons? If anyone has ideas let me know and I can put something together in Illustrator

Or take some of the good ones as default so you don't need to build them yourself.

[sidharthv96]

Solid progress @NicolasNewman 👍

Minor note regarding readability of labels.

I feel the label that goes from top to bottom and right to left is more readable.

---