[websockets] AsyncUpdates more info on architecture

src/Gargantext/Core/AsyncUpdates.hs

@@ -16,6 +16,7 @@ import Protolude
 
 
 {-
+
 I imagine the workflow as follows:
 - somewhere in the code (or in the async job worker) we decide to send
   an update message to all interested users
@@ -27,12 +28,34 @@ I imagine the workflow as follows:
 - the broadcast message is either simple (meaning: hey, we have new
   data, if you want you can send an update request) or we could send
   the changed data already
+
+On the client side it looks more or less like this:
+- specific components decide to subscribe to specific
+  UserNotifications: task component is interested in running tasks (for
+  given node id), tree component is interested in the tree and its
+  first-level children (same for the children components)
+- the components react to events accordingly (usually by pulling in
+  new data)
+
+Thus, for example, the triple (user_id, node_id, "update_tree")
+defines a "update tree for given user and given node" subscription to
+this event, both for server and client. This triple is then the
+"touching point" between client and server. Through that point, update
+messages are sent from server.
+
+Subscription to topics is important IMHO because it allows to target
+clients directly rather than broadcasting messages to everyone. This
+reduces latency and is more secure. At the same time it is a bit more
+complicated because we need to agree on the topic schema both on
+server and client.
+
 -}
     
 
 -- | Various update actions
 data UpdateAction =
-  -- | Update given Servant Job (we currently send a request every second to get job status)
+  -- | Update given Servant Job (we currently send a request every
+  -- | second to get job status).
   --  UpdateJob JobID
   -- | Given parent node id, trigger update of the node and its
   --   children (e.g. list is automatically created in a corpus)
@@ -71,6 +94,9 @@ data ConnectedUser conn =
 
 
 -- | Given a UserNotification and all connected users, send it to
---   interested ones.
+--   interested ones. Possibly we could make this function as part of
+--   a typeclass so that we can decide how to send the notification
+--   based on whether we choose pure WebSockets, NATS or something
+--   else.
 sendNotification :: UserNotification -> [ ConnectedUser conn ] -> m ()
 sendNotification = undefined