README.md

Adding diagrams using mermaid

If diagrams are needed, you can either create them using the tools you like to use, or you can use mermaid to generate diagrams using Markdown-like syntax.

Unfortunately preview of mermaid diagrams is not supported by Github yet. There are supposed to be some browser extension to make it work, but they doesn't seem to be able to render the diagrams correctly in PR views. So for now we will use generated images instead.

To add a diagram generated by mermaid, you should:

1. Add the mermaid Markdown file in the mermaid-diagrams-source directory. Make sure the filename is using .mmd extension.
2. In the root of the project, run the following command:

   make docs/generate/mermaid
   

   It will download the mermaid CLI docker container and generate the diagrams.
3. Insert the image to your doc.