[docs] add documentation about soledad sync process

1 files changed, 32 insertions, 0 deletions

diff --git a/docs/sphinx/sync.rst b/docs/sphinx/sync.rst
new file mode 100644
index 00000000..f243befb
--- /dev/null
+++ b/docs/sphinx/sync.rst
@@ -0,0 +1,32 @@
+Soledad sync process
+====================
+
+Phases of sync:
+
+(1) client acquires knowledge about server state. http GET
+(2) client sends its documents to the server. http POSTs, or a single POST.
+(3) client downloads documents from the server.
+(4) client records its new state on the server.
+
+Originally in u1db:
+    (1) is a GET,
+    (2) and (3) are one POST (send in body, receive in response),
+    (4) is a PUT.
+
+In soledad:
+
+(1) is a GET.
+(2) is either 1 or a series of sequential POSTS.
+  (2.1) encrypt asynchronously
+  (2.2) store in temp sync db
+  (2.3) upload sequentially ***THIS IS SLOW***
+(3) is a series of concurrent POSTS, insert sequentially on local client db.
+  (3.1) download concurrently
+  (3.2) store in temp sync db
+  (3.3) decrypt asynchronously
+  (3.4) insert sequentially in local client db
+(4) is a PUT.
+
+This difference between u1db and soledad was made in order to be able to gracefully interrupt the sync in the middle of the upload or the download.
+
+it is essential that all the uploads and downloads are sequential: documents must be added in order. the download happens in parallel, but then locally they are added sequentially to the local db.