Add basic dev docs for replicator logic

Author: HDegroote

lib/replicator.js

@@ -1,3 +1,27 @@
+/* DEV DOCS
+  Every hypercore has one Replicator object managing its connections to other peers.
+  There is one Peer object per peer connected to the Hypercore.
+  Hypercores do not know about other hypercores, so when a peer is connected to multiple cores, there exists one Peer object per core.
+
+  Hypercore indicates block should be downloaded through methods like Replicator.addRange or Replicator.addBlock
+  Hypercore calls Replicator.updateActivity every time a hypercore session opens/closes
+  Replicator.updateActivity ensures the Hypercore is downloading blocks as expected
+  Replicator keeps track of:
+    - Which blocks need to be downloaded (Replicator._blocks)
+    - Which blocks currently have inflight requests (Replicator._inflight)
+
+  Blocks are requested from remote peers by Peer objects. The flow is:
+    - The replicator's updatePeer method gets called
+    - The replicator detects whether the Peer can accept more requests (for example by checking if it's maxed out on inflight blocks)
+    - The replicator then tells the Peer what to request (e.g. Peer_requestRange or Peer._requestBlock methods)
+
+  The Peer object is responsible for tracking
+    - Which blocks does the Peer have available (tracked in remoteBitfield)
+    - Which blocks are you actively looking for from this peer (tracked in missingBlocks)
+    - How many blocks are currently inflight (tracked in inflight)
+  The Peer uses this information to decide which blocks to request form the peer in response to _requestRange requests and the like.
+*/
+
 const b4a = require('b4a')
 const safetyCatch = require('safety-catch')
 const RandomIterator = require('random-array-iterator')