document read and write path

[ghost]

Would be great to have doc folder so that as a developer i can see how te system works architecturally and its features architecturally.

Tasks: In a doc folder, explain the Read and Write flow and interception points such as Security, Tracing and Logging). It should use a common naming convention. A glossary might be needed. It should delineate if else logic in how each part of the flow works that is pertinent to the outcome. It can have links to code if its pertinent later. It should be written for architectural analysis and not as a how to use perspective.

DOD ( Definition of done):

• Ability to understand the conceptual architecture
• Be enough to conceptualise a refactoring of the architecture in whatever way seems fit going forward.

[jirenius]

Currently I will create a new /docs folder containing:

• res-protocol.md
  Overview of the protocol
  Description of the server stack and how they connect (client, resgate, NATS, microservices)
  Description of core concepts (resources, subscription, query resources, etc.). This may also serve the purpose of glossary
  Request and event flows (including path for read and write) as described in the issue.
• res-service-protocol.md Specification of the protocol used between (micro)service & resgate
  Mostly renaming of the existing resprotocol.md file
• res-client-protocol.md Specification on the protocol used between client & resgate

To describe the flows in the res-protocol.md, sequence diagrams might be used for visual aid. For the conditional logic, one can use "alternatives": https://stackoverflow.com/questions/8114770/how-to-show-if-condition-on-a-sequence-diagram

[jirenius]

Solved in https://github.com/jirenius/resgate/pull/28 Gateway flow sequence diagrams not linked to from README, but available under /docs folder.