docs: add architecture guide to developer docs

[hedi-tej]

Summary

• add architecture guide under docs/source/dev/architecture.md
• add architecture page to docs/source/dev/index.rst
• keep web-related sections

[mockoocy]

Sadly our documentation builder does not compile the mermaid.js code.

Maybe you could just provide the compiled diagrams and just reference them?

[marcus-oscarsson]

Thanks alot, a very nice initiative :) !. Could you add the rendered versions of the images, we don't currently have a mermaid plugin.

[mockoocy]

Well found :)

Renders perfectly now.

[marcus-oscarsson]

Looks pretty good in general, this should be Flask though and not FastAPI :) I think there one or two more instances of FastAPI. But it otherwise looks quite correct

[hedi-tej]

Thanks for catching that. This document was generated last year so maybe those were legacy elements ? Anyway i replaced the fastAPI instances in this doc :)

[marcus-oscarsson]

Suggested change

WS[WebSocket Server]

[marcus-oscarsson]

I would simply remove the WS WebSocket Server and perhaps include it in API[Flask Backend]. Or make another box around the two.

[marcus-oscarsson]

I went through this again and it does for the most part look correct and I think it can be really useful to get an over view of the project. But it should be taken with a pinch of salt its not really accurate but correct on a conceptual level.

I had one more remark on the graph, and it would be great if you could run the mdformat step of the pre-commit step. Then we can merge :)

[mockoocy]

Maybe we could add some remark that the diagrams have been generated based on the existing codebase and written with assist of a coding agent.

Just so that it does not seem authorative, it could help us avoid some potential confusion in the future in case someone were to look at an outdated by then diagram :)

[marcus-oscarsson]

Yes we can add such a comment. But all documentation we add should be revived and accurate for whatever purpose it has. So adding a sort of disclaimer at the same time seems a bit contradictory, but I can understand that it helps.

In that case, perhaps write something like: This documentation was partly generated automatically and is meant to give an architectural overview and idea of the concepts involved and may lack or be some detail.

[mockoocy]

In that case, perhaps write something like: This documentation was partly generated automatically and is meant to give an architectural overview and idea of the concepts involved and may lack or be some detail.

Yes, that's more akin to something I had in mind. I've just overemphasized the part regarding outdateness, which is quite hard to avoid :)

[marcus-oscarsson]

@hedi-tej: We are ready to merge this one if you just look at the linting error, I guess its something small ?

[hedi-tej]

Hello all,

Thank you for your feedback. I just returned from vacation.
This last commit includes the following changes:

• Combined Flask Backend and WebSocket Server into one box in the diagram
• Fixed the linting issue
• Added a disclaimer to clarify the scope of the documentation
  Please let me know if there is anything else that should be addressed.

Best regards,
Hedi

[marcus-oscarsson]

Well done, thanks. I think it will be quite useful for new developers !

[marcus-oscarsson]

Sorry for taking sometime before merging. Thanks for the nice work !