[doc] Add an ADR to improve React representations rendering

[mcharfadi]

Pull request template

General purpose

What is the main goal of this pull request?

• Bug fixes
• New features
• Documentation
• Cleanup
• Tests
• Build / releng

Project management

• Has the pull request been added to the relevant project and milestone? (Only if you know that your work is part of a specific iteration such as the current one)
• Have the priority: and pr: labels been added to the pull request? (In case of doubt, start with the labels priority: low and pr: to review later)
• Have the relevant issues been added to the pull request?
• Have the relevant labels been added to the issues? (area:, difficulty:, type:)
• Have the relevant issues been added to the same project and milestone as the pull request?
• Has the CHANGELOG.adoc been updated to reference the relevant issues?
• Have the relevant API breaks been described in the CHANGELOG.adoc? (Including changes in the GraphQL API)
• In case of a change with a visual impact, are there any screenshots in the CHANGELOG.adoc? For example in doc/screenshots/2022.5.0-my-new-feature.png

Architectural decision records (ADR)

• Does the title of the commit contributing the ADR start with [doc]?
• Are the ADRs mentioned in the relevant section of the CHANGELOG.adoc?

Dependencies

• Are the new / upgraded dependencies mentioned in the relevant section of the CHANGELOG.adoc?
• Are the new dependencies justified in the CHANGELOG.adoc?

Frontend

This section is not relevant if your contribution does not come with changes to the frontend.

General purpose

• Is the code properly tested? (Plain old JavaScript tests for business code and tests based on React Testing Library for the components)

Typing

We need to improve the typing of our code, as such, we require every contribution to come with proper TypeScript typing for both changes contributing new files and those modifying existing files.
Please ensure that the following statements are true for each file created or modified (this may require you to improve code outside of your contribution).

• Variables have a proper type
• Functions’ arguments have a proper type
• Functions’ return type are specified
• Hooks are properly typed:
  • useMutation<DATA_TYPE, VARIABLE_TYPE>(…)
  • useQuery<DATA_TYPE, VARIABLE_TYPE>(…)
  • useSubscription<DATA_TYPE, VARIABLE_TYPE>(…)
  • useMachine<CONTEXT_TYPE, EVENTS_TYPE>(…)
  • useState<STATE_TYPE>(…)
• All components have a proper typing for their props
• No useless optional chaining with ?. (if the GraphQL API specifies that a field cannot be null, do not treat it has potentially null for example)
• Nullable values have a proper type (for example let diagram: Diagram | null = null;)

Backend

This section is not relevant if your contribution does not come with changes to the backend.

General purpose

• Are all the event handlers tested?
• Are the event processor tested?
• Is the business code (services) tested?
• Are diagram layout changes tested?

Architecture

• Are data structure classes properly separated from behavioral classes?
• Are all the relevant fields final?
• Is any data structure mutable? If so, please write a comment indicating why
• Are behavioral classes either stateless or side effect free?

Review

How to test this PR?

Please describe here the various use cases to test this pull request

• Has the Kiwi TCMS test suite been updated with tests for this contribution?

[pcdavid]

Duplicate of line "ADR-156"

[pcdavid]

Not sure what "use lots of interactions" means?

[mcharfadi]

Yes I'll change the phrasing, I wanted to point out representation that have more way to interact with than others (like diagrams)

[sbegaudeau]

Stop putting two empty lines between sentences. A simple line return is enough.

[sbegaudeau]

I can understand in the grand scheme of things how we could use a solution like that but I don't see what would motive it right now.

The changes sended by the back-end could look like the changes used by the ReactFlow renderer meaning for the nodes

That would be a massive change in itself. While it would certainly help with minor operations like moving a node, most of what is possible in a diagram has a sizable impact, potentially changing dozens of elements in a diagram. I'm not even sure that "computing the incremental change" would be faster than just sending the new diagram. I'm not sure which performance problem identified RIGHT NOW you would solve with this.

Our approach to performance improvements will be guided by concrete performance problems identified right now. This ADR involves multiples massive architectural changes on both the backend and the frontend of multiple parts of the code. It may make some good points but it's way too vague and generic.

If you want to move forward with such proposal, when you will have time affected to performance improvement or during a cool down:

• Find and measure a specific performance problem that affects our end users
• Come up with an ADR to solve that specific problem

We could move forward one day with incremental changes sent over the subscription for representations, we could move forward with other kind of changes for tree based representations too but in this state, I don't understand what clear issue this ADR is trying to solve and how it would solve it. The constraints we have one tree based representations and diagram or form based representations are very different and the solution would have to be tailor made for each use case. I feel that this document should probably be 2 or 3 different ADRs but I don't clearly see the performance issue identified for each use case.