[websockets] async update: external/internal communication

src/Gargantext/Core/AsyncUpdates.hs

@@ -17,7 +17,13 @@ import Protolude
 
 {-
 
-I imagine the workflow as follows:
+Please note that we have 2 different notification mechanisms:
+- external (i.e. WebSocket or SSE connection to the frontend)
+- internal (e.g. job workers would like to report either progress or
+  that some node changed in the tree)
+    
+I imagine the workflow as follows (this is a mix of internal and
+external communication):
 - somewhere in the code (or in the async job worker) we decide to send
   an update message to all interested users
 - such an action (UserAction) can be associated with the triggering
@@ -29,7 +35,8 @@ I imagine the workflow as follows:
   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:
+On the client side it looks more or less like this (external
+communication):
 - 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
@@ -49,10 +56,19 @@ 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.
 
+As for internal communication, we don't need topics: we always want to
+get all notifications and process them accordingly (send messages to
+connected users, ignore any messages that would be sent to
+non-connected users).
+
 -}
     
+-------------------------
+-- EXTERNAL COMMUNICATION
+-------------------------
 
--- | Various update actions
+    
+-- | Various topics that users can subscribe to
 data Topic =
   -- | Update given Servant Job (we currently send a request every
   -- | second to get job status).