Add design docs

[inbarbarkai]

No description provided.

[yarons]

I'm looking at all the possible ways of generating documentation, there are several:

1. Using some online converter that doesn't require any GH Actions: https://github.com/jonashackt/plantuml-markdown - requires separating the UML from the Markdown.
2. GH Actions (Which I'm still trying to understand how to deploy to GitHub Pages/Wiki when done): https://github.com/marketplace/actions/generate-plantuml - it only creates SVG out of the UMLs you already have and replaces the @plantuml expression with the SVG that was generated next to it.
3. Switch to GitLab.
4. Switch to Mermain.

[inbarbarkai]

Mermaid does not support the features I used in PlantUML.
I don't see myself changing tools to write documentation.

I have no issue with separating the diagrams from the markdown, just point me to an explanation on how.

[yarons]

OK So we're looking at options 1 or 2.
The link in option 1 explaining the separation assuming we're choosing this path.
Option number 2 creates an additional folder for the generated SVG files and links the relevant sections in the MD to this SVG image as an external resource.
Those 2 links explain everything we need to do to make it work, I'll just need to adjust it for some tests and possibly set your branch to the documentation branch instead of the main one.
The official GitHub Pages offering focuses on Jekyll, which is pretty neat and also has a plugin that supports PlantUML.

This is my ChatGPT about this subject (I narrowed down the option and for some reason the implementation transformed drastically): https://chat.openai.com/share/47acfe3b-be0d-4bc5-94df-d9a891805262

[yarons]

As discussed, we'll skip the first option to avoid collisions due to branch naming, I'll work on that.

[yarons]

As discussed, it looks great, I'd like to talk to you about the current architecture and what are the advantages of this proposal, thanks :)