Documentation

doc/design.md

@@ -9,6 +9,8 @@ changes you made on them on other synced devices and on your online Cozy.
 Metadata workflow
 -----------------
 
+![Metadata workflow](workflow.png)
+
 Cozy-desktop is a nodejs app, written in coffeescript to be coherent with
 other cozy codes. As its core, there is a pouchdb database used to keep
 metadata about files and folders.
@@ -31,12 +33,19 @@ If a new file is added, cozy-desktop will ask one side to provide a nodejs
 readable stream, and the other side will pipe it to its destination: a file on
 the local filesytem, or a binary document on the remote couchdb.
 
-**TODO:**
 
-- add a schema
-- explain how we avoid loops of metadata updates
-- explain when conflicts happen and how they are resolved
-- explain the special trick for renames and moves
+Conflicts
+---------
+
+Conflicts can happen. For example, when cozy-desktop is stopped, a file is
+added on the remote cozy and a different file is added to the local filesystem
+at the same path. When cozy-desktop will start, it will detect that both the
+remote cozy instance and the local filesystem have a file for the same path.
+
+The conflict resolution is very simple: one of those file is renamed with a
+`-conflict` suffix. A more evolved solution would have been very hard to
+secure. And bugs in this part mean losing data, which is very bad. So, we
+don't try to be smart and prefer a robust solution.
 
 
 Documents schema

doc/workflow.ditaa

@@ -0,0 +1,16 @@
+       Watcher                        Changes feed
+       (chokidar)    /-------------\     (CouchDB)
+       +------------>|    Merge    |<------------+
+       |             \------+------/             |
+       |                    |                    |
+       |                    |                    |
+       |                    V                    |
+/------+------\      /-------------\      /------+------\
+| File system |      |   PouchDB   |      | Remote Cozy |
+\-------------/      \------+------/      \-------------/
+       ^                    |                    ^
+       |                    |                    |
+       |                    V                    |
+       |             /-------------\             |
+       +-------------+    Sync     +-------------+
+                     \-------------/